---

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).

• In typesafe mode, OSerial uses a verbose, human-readable output format which includes type names of objects. When the output is later deserialized, ISerial checks the type names to verify that data are being read into objects of the proper types.

• In binary mode, OSerial uses a compact, well-defined, non-human-readable, non-typesafe representation, defined recursively as follows. This representation is stable and platform- and language-independent, so it can be read and written by any software (not just NMSTL) and can be used as the basis for simple file formats and protocols. A Java implementation is provided in the java directory.
  • A scalar is serialized as an n-byte, network-order integer, where n is 1 for bool, 2 for short, 4 for int or long, and 8 for long long.
  • A string is serialized as a 4-byte, network-order length field, plus the contents of the string.
  • A pair<A, B> is serialized as A followed by B (e.g., a pair<short, string> is a two-byte integer, followed by a string [which is a four-byte length field followed by the string contents]).
  • An STL container is serialized as a four-byte integer which is the number of elements in the container, followed by the serialization of each element of the container.
  • An arbitrary object T is serialized according to its freeze method, which generally writes the class's instance variables in order.
  • A ptr<T> is serializable only if T has uses the serialization facility described in Serialization and inheritance, below. First a 1-byte boolean value is written, 0 if the pointer is null or 1 if not. If the pointer is non-null, the typeid of the actual object is written (e.g., 200 for cars below); then the object is serialized as per its freeze method.
• In compact mode, OSerial uses an even more compact representation using variable-length integer fields.

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:

• Pick a type which you will use to differentiate classes in the hierarchy (e.g., long). This is called the typeid_type for the hierarchy.

• Pick a unique value of this type, called a type-ID, for each class (e.g., 100, 200, and 300 for automobile, car, and truck respectively.

• In the declaration for your base class T, use the NMSTL_SERIAL_BASE(T, typeid_type, fields), e.g.:

   class automobile {
     private:
       int wheels;
       double length;
         ...
       NMSTL_SERIAL_BASE(automobile, long, << wheels << length);
   };
  

• In each subclass U, use the NMSTL_SERIAL_SUBCLASS(supertype, U, fields) macro, e.g.:

   class truck : public automobile {
     private:
       float gross_capacity;
         ...
       NMSTL_SERIAL_SUBCLASS(truck, automobile, << gross_capacity);
   };
  

• For each class T with an NMSTL_SERIAL_BASE or NMSTL_SERIAL_SUBCLASS, put a NMSTL_SERIAL_DEFINE(T, the_typeid) in a .cc file, where the_typeid is the type-ID you selected for that class (100, 200, or 300 in this example).

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 (  T    s )  [protected]

template<typename T> void OSerial::write_compact_unsigned (  T    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:

• serial

---