Public Member Functions | List of all members
blaze::Archive< Stream > Class Template Reference

Binary archive for the portable serialization of data.The Archive class implements the functionality to create platform independent, portable, representations of arbitrary C++ data structures. The resulting binary data structures can be used to reconstitute the data structures in a different context, on another platform, etc. More...

#include <Archive.h>

Inherits blaze::NonCopyable.

Public Member Functions

template<typename T >
EnableIf_< IsNumeric< T >, Archive< Stream > & > operator<< (const T &value)
 Serializes the given built-in data value and writes it to the archive. More...
 
template<typename T >
DisableIf_< IsNumeric< T >, Archive< Stream > & > operator<< (const T &value)
 Serializes the user-defined object and writes it to the archive. More...
 
template<typename T >
EnableIf_< IsNumeric< T >, Archive< Stream > & > operator>> (T &value)
 Deserializes a value of built-in data type and reads it from the archive. More...
 
template<typename T >
DisableIf_< IsNumeric< T >, Archive< Stream > & > operator>> (T &value)
 Deserializes an object of user-defined data type and reads it from the archive. More...
 
template<typename Type >
EnableIf_< IsNumeric< Type >, Archive< Stream > & > write (const Type *array, size_t count)
 Writing an array of values to the stream. More...
 
template<typename Type >
EnableIf_< IsNumeric< Type >, Archive< Stream > & > read (Type *array, size_t count)
 Reading an array of values from the stream. More...
 
Constructors
template<typename... Args>
 Archive (Args &&...args)
 Creating an archive with an internal stream resource. More...
 
 Archive (Stream &stream)
 Creating an archive with an external stream resource. More...
 
Operators
 operator bool () const
 Returns the current state of the archive. More...
 
bool operator! () const
 Returns the negated state of the archive. More...
 
Serialization functions
template<typename T >
EnableIf_< IsNumeric< T >, Archive & > operator<< (const T &value)
 
template<typename T >
DisableIf_< IsNumeric< T >, Archive & > operator<< (const T &value)
 
template<typename T >
EnableIf_< IsNumeric< T >, Archive & > operator>> (T &value)
 
template<typename T >
DisableIf_< IsNumeric< T >, Archive & > operator>> (T &value)
 
template<typename Type >
EnableIf_< IsNumeric< Type >, Archive & > write (const Type *array, size_t count)
 
template<typename Type >
EnableIf_< IsNumeric< Type >, Archive & > read (Type *array, size_t count)
 
Utility functions
Stream::int_type peek () const
 Reads the next character from the input stream without extracting it. More...
 
bool good () const
 Checks if no error has occurred, i.e. I/O operations are available. More...
 
bool eof () const
 Checks if end-of-file (EOF) has been reached. More...
 
bool fail () const
 Checks if a recoverable error has occurred. More...
 
bool bad () const
 Checks if a non-recoverable error has occurred. More...
 
std::ios_base::iostate rdstate () const
 Returns the current state flags settings. More...
 
void setstate (std::ios_base::iostate state)
 Sets the state flags to a specific value. More...
 
void clear (std::ios_base::iostate state=std::ios_base::goodbit)
 Clears error and eof flags. More...
 

Private Attributes

Member variables
std::unique_ptr< Stream > ptr_
 The dynamically allocated stream resource. More...
 
Stream & stream_
 Reference to the bound stream.
 

Detailed Description

template<typename Stream>
class blaze::Archive< Stream >

Binary archive for the portable serialization of data.

The Archive class implements the functionality to create platform independent, portable, representations of arbitrary C++ data structures. The resulting binary data structures can be used to reconstitute the data structures in a different context, on another platform, etc.

The following example demonstrates the Archive class by means of a C-style POD data structure:

struct POD {
int i;
unsigned int u;
float f;
double d;
};

The archive already supports the (de-)serialization of built-in data types. In order to be able to serialize the POD data structure, i.e. to convert it into a binary representation that can stored or transfered to other machines, the according serialize and deserialize function have to be implemented:

template< typename Archive >
void serialize( Archive& archive, const POD& pod )
{
archive << pod.i << pod.u << pod.f << pod.d;
}
template< typename Archive >
void deserialize( Archive& archive, POD& pod )
{
archive >> pod.i >> pod.u >> pod.f >> pod.d;
}

The serialize function implements the conversion from the POD to a binary representation, the deserialize function implements the reverse conversion from a binary representation to a POD. Note that it is important to write the values to the archive in exactly the same order as the values are read from the archive!

With these two functions it is already possible to serialize a POD object:

int main()
{
// Creating a binary representation of a POD in the file 'filename'
{
POD pod;
// ... Initialize the POD with values
Archive<std::ofstream> archive( "filename", std::ofstream::trunc );
archive << pod;
}
// Reconstituting the POD from the binary representation
{
POD pod;
Archive<std::ifstream> archive( "filename" );
archive >> pod;
}
}

Each archive has to be bound to either an output or input stream. In the example, the archive is bound to a file output stream that is created by passing the file name and the according flags to the archive. Subsequently, the archive can be used like an output stream to write the POD data structure to the file called 'filename'.

The reverse conversion from the binary representation contained in the file to the POD data structure can be achieved by binding an archive to a file input stream. Subsequently, the archive can be used as an input stream to read the POD from file.

Note that the Archive class can be bound to any kind of input or output stream (or also iostream) that supports the standard write or read functions, respectively. Therefore the serialization of a C++ data structure is not restricted to binary files, but allows for any possible destination.

Constructor & Destructor Documentation

template<typename Stream >
template<typename... Args>
blaze::Archive< Stream >::Archive ( Args &&...  args)
inlineexplicit

Creating an archive with an internal stream resource.

Parameters
argsThe stream arguments.

This function creates a new archive with an internal stream resource, which is created based on the given arguments args.

template<typename Stream >
blaze::Archive< Stream >::Archive ( Stream &  stream)
inlineexplicit

Creating an archive with an external stream resource.

Parameters
streamThe stream to be bound to the archive.

This function creates a new archive with an external stream resource, which is bound to the archive. Note that the stream is NOT automatically closed when the archive is destroyed.

Member Function Documentation

template<typename Stream >
bool blaze::Archive< Stream >::bad ( ) const
inline

Checks if a non-recoverable error has occurred.

Returns
true in case a non-recoverable error has occurred, false otherwise.
template<typename Stream >
void blaze::Archive< Stream >::clear ( std::ios_base::iostate  state = std::ios_base::goodbit)
inline

Clears error and eof flags.

Parameters
stateThe new error state flags setting.
Returns
void
template<typename Stream >
bool blaze::Archive< Stream >::eof ( ) const
inline

Checks if end-of-file (EOF) has been reached.

Returns
true in case end-of-file has been reached, false otherwise.
template<typename Stream >
bool blaze::Archive< Stream >::fail ( ) const
inline

Checks if a recoverable error has occurred.

Returns
true in case a recoverable error has occurred, false otherwise.
template<typename Stream >
bool blaze::Archive< Stream >::good ( ) const
inline

Checks if no error has occurred, i.e. I/O operations are available.

Returns
true in case no error has occurred, false otherwise.
template<typename Stream >
blaze::Archive< Stream >::operator bool ( ) const
inline

Returns the current state of the archive.

Returns
false in case an input/output error has occurred, true otherwise.

This operator returns the current state of the Archive based on the state of the bound stream. In case an input/output error has occurred, the operator returns false, otherwise it returns true.

template<typename Stream >
bool blaze::Archive< Stream >::operator! ( ) const
inline

Returns the negated state of the archive.

Returns
true in case an input/output error has occurred, false otherwise.

This operator returns the negated state of the Archive based on the state of the bound stream. In case an input/output error has occurred, the operator returns true, otherwise it returns false.

template<typename Stream>
template<typename T >
EnableIf_< IsNumeric<T>, Archive<Stream>& > blaze::Archive< Stream >::operator<< ( const T &  value)

Serializes the given built-in data value and writes it to the archive.

Parameters
valueThe built-in data value to be serialized.
Returns
Reference to the archive.
template<typename Stream>
template<typename T >
DisableIf_< IsNumeric<T>, Archive<Stream>& > blaze::Archive< Stream >::operator<< ( const T &  value)

Serializes the user-defined object and writes it to the archive.

Parameters
valueThe user-defined object to be serialized.
Returns
Reference to the archive.
template<typename Stream>
template<typename T >
EnableIf_< IsNumeric<T>, Archive<Stream>& > blaze::Archive< Stream >::operator>> ( T &  value)

Deserializes a value of built-in data type and reads it from the archive.

Parameters
valueThe built-in data value to be read from the archive.
Returns
Reference to the archive.
template<typename Stream>
template<typename T >
DisableIf_< IsNumeric<T>, Archive<Stream>& > blaze::Archive< Stream >::operator>> ( T &  value)

Deserializes an object of user-defined data type and reads it from the archive.

Parameters
valueThe user-defined object to be read from the archive.
Returns
Reference to the archive.
template<typename Stream >
Stream::int_type blaze::Archive< Stream >::peek ( ) const
inline

Reads the next character from the input stream without extracting it.

Returns
The next character contained in the input stream.
template<typename Stream >
std::ios_base::iostate blaze::Archive< Stream >::rdstate ( ) const
inline

Returns the current state flags settings.

Returns
The current state flags settings.
template<typename Stream>
template<typename Type >
EnableIf_< IsNumeric<Type>, Archive<Stream>& > blaze::Archive< Stream >::read ( Type *  array,
size_t  count 
)
inline

Reading an array of values from the stream.

Parameters
arrayPointer to the first element of the array.
countThe number of elements in the array.

This function reads count elements of the numeric type Type from the archive and writes them to the array. Note that the function can only be used for arrays of numeric type. Also note that the read function does not allocate memory, but expects that array provides storage for at least count elements of type Type!

template<typename Stream >
void blaze::Archive< Stream >::setstate ( std::ios_base::iostate  state)
inline

Sets the state flags to a specific value.

Parameters
stateThe new error state flags setting.
Returns
void
template<typename Stream>
template<typename Type >
EnableIf_< IsNumeric<Type>, Archive<Stream>& > blaze::Archive< Stream >::write ( const Type *  array,
size_t  count 
)
inline

Writing an array of values to the stream.

Parameters
arrayPointer to the first element of the array.
countThe number of elements in the array.

This function writes count elements of the numeric type Type from the given array to the archive. Note that the function can only be used for arrays of numeric type!

Member Data Documentation

template<typename Stream>
std::unique_ptr<Stream> blaze::Archive< Stream >::ptr_
private

The dynamically allocated stream resource.

In case no stream is bound to the archive from the outside, this smart pointer handles the internally allocated stream resource.


The documentation for this class was generated from the following file: