All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 > & >::Type 
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 > & >::Type 
operator<< (const T &value)
 Serializes the user-defined object and writes it to the archive. More...
 
template<typename T >
EnableIf< IsNumeric< T >
, Archive< Stream > & >::Type 
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 > & >::Type 
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 > & >::Type 
write (const Type *array, size_t count)
 Writing an array of values to the stream. More...
 
template<typename Type >
EnableIf< IsNumeric< Type >
, Archive< Stream > & >::Type 
read (Type *array, size_t count)
 Reading an array of values from the stream. More...
 
Constructors
 Archive ()
 Creating an archive with an internal stream resource. More...
 
template<typename A1 >
 Archive (const A1 &a1)
 Creating an archive with an internal stream resource. More...
 
template<typename A1 , typename A2 >
 Archive (const A1 &a1, const A2 &a2)
 Creating an archive with an internal stream resource. More...
 
template<typename A1 , typename A2 , typename A3 >
 Archive (const A1 &a1, const A2 &a2, const A3 &a3)
 Creating an archive with an internal stream resource. More...
 
template<typename A1 , typename A2 , typename A3 , typename A4 >
 Archive (const A1 &a1, const A2 &a2, const A3 &a3, const A4 &a4)
 Creating an archive with an internal stream resource. More...
 
template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 >
 Archive (const A1 &a1, const A2 &a2, const A3 &a3, const A4 &a4, const A5 &a5)
 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 & >::Type 
operator<< (const T &value)
 
template<typename T >
DisableIf< IsNumeric< T >
, Archive & >::Type 
operator<< (const T &value)
 
template<typename T >
EnableIf< IsNumeric< T >
, Archive & >::Type 
operator>> (T &value)
 
template<typename T >
DisableIf< IsNumeric< T >
, Archive & >::Type 
operator>> (T &value)
 
template<typename Type >
EnableIf< IsNumeric< Type >
, Archive & >::Type 
write (const Type *array, size_t count)
 
template<typename Type >
EnableIf< IsNumeric< Type >
, Archive & >::Type 
read (Type *array, size_t count)
 
Utility functions
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
UniquePtr< 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 >
blaze::Archive< Stream >::Archive ( )
inlineexplicit

Creating an archive with an internal stream resource.

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

template<typename Stream >
template<typename A1 >
blaze::Archive< Stream >::Archive ( const A1 &  a1)
inlineexplicit

Creating an archive with an internal stream resource.

Parameters
a1The first stream argument.

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

template<typename Stream >
template<typename A1 , typename A2 >
blaze::Archive< Stream >::Archive ( const A1 &  a1,
const A2 &  a2 
)
inlineexplicit

Creating an archive with an internal stream resource.

Parameters
a1The first stream argument.
a2The second stream argument.

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

template<typename Stream >
template<typename A1 , typename A2 , typename A3 >
blaze::Archive< Stream >::Archive ( const A1 &  a1,
const A2 &  a2,
const A3 &  a3 
)
inlineexplicit

Creating an archive with an internal stream resource.

Parameters
a1The first stream argument.
a2The second stream argument.
a3The third stream argument.

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

template<typename Stream >
template<typename A1 , typename A2 , typename A3 , typename A4 >
blaze::Archive< Stream >::Archive ( const A1 &  a1,
const A2 &  a2,
const A3 &  a3,
const A4 &  a4 
)
inlineexplicit

Creating an archive with an internal stream resource.

Parameters
a1The first stream argument.
a2The second stream argument.
a3The third stream argument.
a4The fourth stream argument.

This function creates a new archive with an internal stream resource, which is created based on the given arguments a1, a2, a3, and a4.

template<typename Stream >
template<typename A1 , typename A2 , typename A3 , typename A4 , typename A5 >
blaze::Archive< Stream >::Archive ( const A1 &  a1,
const A2 &  a2,
const A3 &  a3,
const A4 &  a4,
const A5 &  a5 
)
inlineexplicit

Creating an archive with an internal stream resource.

Parameters
a1The first stream argument.
a2The second stream argument.
a3The third stream argument.
a4The fourth stream argument.
a5The fifth stream argument.

This function creates a new archive with an internal stream resource, which is created based on the given arguments a1, a2, a3, a4, and a5.

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>& >::Type 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>& >::Type 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>& >::Type 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>& >::Type 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 >
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>& >::Type 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>& >::Type 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>
UniquePtr<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: