Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members  

OSerial Class Reference

Inherited by OSerialStream, and OSerialString.

List of all members.


Detailed Description

An OSerial is analogous to an ObjectOutputStream in Java.

To serialize objects:

  1. Create an ostream object.
  2. Create an OSerial object pointing to that ostream.
  3. Write objects to the OSerial object using the << operator.
You can write C++ primitives and STL containers to OSerial objects. You can also serializers/deserialize objects you declare by using the NMSTL_SERIAL macro, as in the example below.

There are three serialization modes (selectable in the second argument of the constructor).

Serialization and inheritance

Normally you will serialize and deserialize objects by value, just as objects are read from and written to iostreams by value. For instance, to read an integer, use

 int x = ...;
 OSerialString out;
 out << x;  // Not &x

 ISerialString in( out.str() );
 in >> x;   // Not &x

However, this won't quite work for hierarchies of objects. For instance: if car and truck both derive from a common superclass, automobile, then you can't read a serialized truck into a generic automobile object: in C++ types of objects cannot be fixed.

 car buick("BUICK");
 OSerialString oss;
 oss << buick;

 automobile aut;
 ISerialString iss(oss.str());
 iss >> aut; // Serialization error!  Can't change type of aut to car at runtime

Fortunately, NMSTL provides a facility for read and writing objects of arbitrary type via pointers, so that when you write any sort of automobile object, the serializer for the actual type of the object (car) is invoked, and when you read any sort of automobile object back in, the correct subtype is automatically constructed and deserialized.

To use this facility:

Example

 class my_class {
   public:
     int member1;
     map< string, vector<int> > member2;

     NMSTL_SERIAL(my_class, << member1 << member2);
 };

 int main() {
     my_class obj;

       ...

     OSerialString out;
     out << obj;

       ...

     // read it back in from the string
     my_class obj2;
     ISerialString in(out.str());
     in >> obj2;
     if (in)
         cout << "Success!" << endl;
     else
         cout << "Failure (" << in.error() << ")!" << endl;
 }

Example using containers

 map<int, string> my_map;
 my_map[1] = "ONE";
 my_map[2] = "TWO";
 my_map[3] = "THREE";

 OSerialString out1;
 out1 << my_map;

 // Writes:
 //   00 00 00 03    (number of elements)
 //   00 00 00 01    (key of first element)
 //   00 00 00 03    (length of first element data)
 //   4F 4E 45       ("ONE")
 //   00 00 00 02    (key of second element)
 //   00 00 00 03    (length of first element data)
 //   54 57 4F       ("TWO")
 //   00 00 00 03    (key of second element)
 //   00 00 00 05    (length of second element data)
 //   54 48 52 45 45 ("THREE")

 OSerialStream out2;
 out2.serialize(my_map.begin(), my_map.end());
 // Writes exactly the same thing, except without the number
 // of elements.

To deserialize out1 and out2:

 ISerialString in1(out1.str());
 map<int, string> my_new_map_1;
 in1 >> my_new_map_1;

 ISerialString in2(out2.str());
 map<int, string> my_new_map_2;
 // calls my_new_map_2.insert() for each element
 in2.insert_into(my_new_map_2);

 // Or even:
 ISerialString in2alt(out2.str());
 vector<pair<int, string> > my_new_map_2alt;
 // cals my_new_map_2alt.push_back() for each element
 in2alt.push_back_into(my_new_map_2alt);


Public Types

enum  {
  typesafe, readable, binary, compact,
  nosignature = 0x10
}
 Flag parameters that may be used when constructing an OSerial object. More...


Public Methods

 OSerial (int mode=typesafe)
 Constructor.

virtual ~OSerial ()
 operator const void * () const
 Returns a null value if an error has occured, or a non-null value if serialization has succeeded.

int get_mode () const
 Returns the mode being used to serialize data.

Status stat () const
 Returns an error description if some aspect of serialization has failed.

void set_error (const string &s)
 Indicates that an aspect of serialization has failed and sets the error description.

template<class InputIterator> OSerial & serialize (InputIterator begin, InputIterator end)
 Serializes a set of objects in succession.

template<class T> OSerial & operator<< (const T &t)
 The operator used to serialize objects.


Protected Methods

virtual void put (int ch)=0
virtual void put (const char *ch, unsigned int len)=0
void put (const string &s)
void put (const char *ch)
template<typename T> void freeze_as_string (const T &t)
template<typename T> void default_freeze (const T &t)
template<typename T> void write_compact_signed (T s)
template<typename T> void write_compact_unsigned (T s)
template<class T> void default_freeze (const ptr< T > &t)
void default_freeze (const char *s)
void default_freeze (const string &s)
void default_freeze (constbuf s)
template<typename T, typename U> void default_freeze (const pair< T, U > &p)
template<typename Container> void default_freeze_container (const Container &c)
template<typename T> void default_freeze (const vector< T > &t)
template<typename T, typename U> void default_freeze (const map< T, U > &t)
template<typename T> void default_freeze (const set< T > &t)
void write_type (const char *type, unsigned int len)
void init ()

Protected Attributes

Status st
int mode
bool nosig


Member Enumeration Documentation

anonymous enum
 

Flag parameters that may be used when constructing an OSerial object.

Enumeration values:
typesafe  Use the verbose, typesafe representation for output.
readable  Use a readable but non-typesafe output format.
binary  Use a more compact, non-human-readable, typesafe representation for output.
compact  Use a very compact, non-human-readable, typesafe representation for output.
nosignature 


Constructor & Destructor Documentation

OSerial::OSerial int    mode = typesafe
 

Constructor.

Parameters:
mode  the mode in which to serialize data (typesafe, binary, or compact)

virtual OSerial::~OSerial   [virtual]
 


Member Function Documentation

template<typename T>
void OSerial::default_freeze const set< T > &    t [protected]
 

template<typename T, typename U>
void OSerial::default_freeze const map< T, U > &    t [protected]
 

template<typename T>
void OSerial::default_freeze const vector< T > &    t [protected]
 

template<typename T, typename U>
void OSerial::default_freeze const pair< T, U > &    p [protected]
 

void OSerial::default_freeze constbuf    s [protected]
 

void OSerial::default_freeze const string &    s [protected]
 

void OSerial::default_freeze const char *    s [protected]
 

template<class T>
void OSerial::default_freeze const ptr< T > &    t [protected]
 

template<typename T>
void OSerial::default_freeze const T &    t [protected]
 

template<typename Container>
void OSerial::default_freeze_container const Container &    c [protected]
 

template<typename T>
void OSerial::freeze_as_string const T &    t [protected]
 

int OSerial::get_mode   const
 

Returns the mode being used to serialize data.

void OSerial::init   [protected]
 

OSerial::operator const void *   const
 

Returns a null value if an error has occured, or a non-null value if serialization has succeeded.

Exists to facilitate the "if (my_oserial) { ... }" metaphor to test whether an error has occurred on my_oserial.

template<class T>
OSerial& OSerial::operator<< const T &    t
 

The operator used to serialize objects.

void OSerial::put const char *    ch [protected]
 

void OSerial::put const string &    s [protected]
 

virtual void OSerial::put const char *    ch,
unsigned int    len
[protected, pure virtual]
 

Implemented in OSerialStream, and OSerialString.

virtual void OSerial::put int    ch [protected, pure virtual]
 

Implemented in OSerialStream, and OSerialString.

template<class InputIterator>
OSerial& OSerial::serialize InputIterator    begin,
InputIterator    end
 

Serializes a set of objects in succession.

void OSerial::set_error const string &    s
 

Indicates that an aspect of serialization has failed and sets the error description.

Status OSerial::stat   const
 

Returns an error description if some aspect of serialization has failed.

template<typename T>
void OSerial::write_compact_signed   s [protected]
 

template<typename T>
void OSerial::write_compact_unsigned   s [protected]
 

void OSerial::write_type const char *    type,
unsigned int    len
[protected]
 


Member Data Documentation

int OSerial::mode [protected]
 

bool OSerial::nosig [protected]
 

Status OSerial::st [protected]
 


The documentation for this class was generated from the following file:
Generated on Fri Dec 20 13:35:11 2002 for NMSTL