Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members

s11n::data_node Class Reference

data_node is the next generation of s11n::s11n_node. More...

#include <data_node.h>

List of all members.

Public Types

typedef std::map< std::string,
std::string > 
map_type
 The map type this object uses to store items internally.

typedef map_type::value_type value_type
 A pair type used to store key/value properties internally.

typedef map_type::key_type key_type
 For compatibility with std::map.

typedef map_type::mapped_type mapped_type
 For compatibility with std::map.

typedef std::vector< data_node * > child_list_type
 The container type used to store this object's children.

typedef map_type::iterator iterator
 For iterating over properties using STL conventions.

typedef map_type::const_iterator const_iterator
 For iterating over properties using STL conventions.


Public Member Functions

 data_node ()
 Creates a new node with an empty name() and an impl_class() of "s11n::data_node".

 data_node (const std::string &name)
 Creates a new node with the given name() and an impl_class() of "s11n::data_node".

 data_node (const std::string &name, const std::string implclass)
 Creates a new node with the given name() and and impl_class().

 ~data_node ()
 Destroys all child objects owned by this object, freeing up their resources.

data_nodeoperator= (const data_node &rhs)
 See copy().

 data_node (const data_node &rhs)
 See copy().

child_list_typechildren ()
 Returns a list of the data_node children of this object.

const child_list_typechildren () const
 The const form of children().

void clear ()
 Removes all properties and deletes all children from this object, freeing up their resources.

void reset ()
 older name for clear().

void impl_class (const std::string &n)
 Defines the class name which should be used as the implementation for the node when it is deserialize()d.

std::string impl_class () const
 Returns the implementation class name set via impl_class().

void name (const std::string &n)
 The name which should be used as the key for storing the node.

std::string name () const
 Returns this node's name, as set via name(string).

const mapped_type operator[] (const key_type &key) const
 std::string propval = node["bar"] is functionally identical to node.get_string("bar").

mapped_typeoperator[] (const key_type &key)
 Untested.

void insert (const value_type &)
 For compatibility with std::map.

std::string get_string (const std::string &key, const std::string &defaultVal=std::string()) const
 Returns the value for key, or defaultVal if the key is not set.

void set_string (const std::string &key, const std::string &val)
 Sets the given key to the given value.

template<typename T> void set (const std::string &key, const T &val)
 See set_string().

void set (const char *key, const char *val)
 The <const char *> variants of get() and set() are to help the developer avoid having to cast so much and to help out compilers which have mediocre template support.

void set (const std::string &key, const char *val)
 Overloaded for strings-via-streams reaons.

void set (const char *key, const std::string &val)
 Overloaded for strings-via-streams reaons.

template<typename T> T get (const std::string &key, const T &defaultval) const
 See get_string().

std::string get (const char *key, const char *val) const
 get(): see set( const char *, const char * ).

std::string get (const std::string &key, const char *val) const
 Overloaded for strings-via-streams reasons.

std::string get (const char *key, const std::string &val) const
 Overloaded for strings-via-streams reasons.

bool is_set (const std::string &key) const
 Returns true if this object contains the given property, else false.

void unset (const std::string &key)
 Removes the given property from this object.

void set_bool (const std::string &key, bool val)
 set_bool() is provided to work around a potential compiler warning:

bool get_bool (const std::string &key, bool defaultVal) const
 get_bool(key) returns true if key's value is true, as evaluated by the static function bool_val().

iterator find (const std::string &key)
 Returns end() if the key is not in our map, otherise it returns that iterator.

iterator begin ()
 Returns the first item in the data map.

const_iterator begin () const
 Returns a const_iterator pointing at this object's first property.

iterator end ()
 The after-the-end iterator for the data map.

const_iterator end () const
 The after-the-end iterator for the data map.

map_typemap ()
 Returns the internally-used map_type (see the typedefs).

const map_typemap () const
 Returns the internally-used map_type (see the typedefs).

size_t size () const
 Returns the number of properties in this object.


Static Public Member Functions

bool bool_val (const std::string &key)
 Returns the bool value of the passed string.


Detailed Description

data_node is the next generation of s11n::s11n_node.

It is a pure container, without and de/serialization-related methods. It is non-polymorphic, in contrast to s11n_node.

It is purely experimental at this point.

This type is a reference implementation for the functionality required of data nodes by the s11n core framework. Any type which conforms to this class' interface/conventions should be usable by s11n::serialize() and related functions.

Common conventions for types "convetionally compatible" with data_node are listed below.

More specific conventions will be detailed later in the library manual.

Definition at line 275 of file data_node.h.


Member Typedef Documentation

typedef std::vector<data_node *> s11n::data_node::child_list_type
 

The container type used to store this object's children.

It contains (data_node *).

While the exact type is not guaranteed, it is guaranteed to obey the most-commonly-used std::list/vector conventions: push_back(), erase(), etc.

Definition at line 306 of file data_node.h.

typedef map_type::const_iterator s11n::data_node::const_iterator
 

For iterating over properties using STL conventions.

Dereferences to a value_type object.

Definition at line 322 of file data_node.h.

typedef map_type::iterator s11n::data_node::iterator
 

For iterating over properties using STL conventions.

Dereferences to a value_type object.

Definition at line 314 of file data_node.h.


Constructor & Destructor Documentation

s11n::data_node::data_node  ) 
 

Creates a new node with an empty name() and an impl_class() of "s11n::data_node".

This node is functionally useless until it's name is set, as nodes with empty names are not supported by any current i/o parsers.

s11n::data_node::data_node const std::string &  name,
const std::string  implclass
 

Creates a new node with the given name() and and impl_class().

Does not throw.

s11n::data_node::~data_node  ) 
 

Destroys all child objects owned by this object, freeing up their resources.

Does not throw.

s11n::data_node::data_node const data_node rhs  ) 
 

See copy().

Does not throw.


Member Function Documentation

iterator s11n::data_node::begin  ) 
 

Returns the first item in the data map.

You can use this to iterate, STL-style:

   data_node::iterator it = node.begin();
   for( ; node.end() != it; ++it ) { ... }
 

Note that the iterator represents a value_type (std::pair), so use (*it).first to get the key and (*it).second to get the value.

bool s11n::data_node::bool_val const std::string &  key  )  [static]
 

Returns the bool value of the passed string.

The following string values are considered equal to true:

true, TRUE, True yes, YES, Yes, y, Y 1

Anything else evaluates to false.

Case IS significant!

child_list_type& s11n::data_node::children  ) 
 

Returns a list of the data_node children of this object.

The caller should not delete any pointers from this list unless he also removes the pointers from the list, or else they will get double-deleted later. In practice it is (almost) never necessary for client code to manipulate this list directly.

See node_child_simple_formatter<> for a funcfor designed to quickly serialize lists such as this one.

void s11n::data_node::clear  ) 
 

Removes all properties and deletes all children from this object, freeing up their resources.

Any pointers to children of this object become invalided by a call to this function (they get deleted). Since client code doesn't normally hold pointers to data_node children this should not be a practical problem. This is normally only used in test code, not client code.

Referenced by reset().

iterator s11n::data_node::find const std::string &  key  ) 
 

Returns end() if the key is not in our map, otherise it returns that iterator.

Use the iterator's 'first' member to get the key and 'second' to get at it's value.

std::string s11n::data_node::get const char *  key,
const char *  val
const [inline]
 

get(): see set( const char *, const char * ).

Same notes apply.

Definition at line 625 of file data_node.h.

References get_string().

template<typename T>
T s11n::data_node::get const std::string &  key,
const T &  defaultval
const [inline]
 

See get_string().

This function is identical except that the returned string is converted to type T. If this type is not possible it will fail at compile time. A value-conversion failure, on the other hand, is not caught at compile time. If value conversion fails then defaultval is returned. This can be interpretted as an error value if the client so chooses, and it is often helpful to pass a known-invalid value here for that purpose.

Definition at line 616 of file data_node.h.

References s11n::from_string(), get(), and get_string().

Referenced by get().

std::string s11n::data_node::get_string const std::string &  key,
const std::string &  defaultVal = std::string()
const
 

Returns the value for key, or defaultVal if the key is not set.

Maintenance note: this is the "master" getter. Almost all other getXXX() functions call this one, so do not call them from inside this function.

Referenced by get().

void s11n::data_node::impl_class const std::string &  n  ) 
 

Defines the class name which should be used as the implementation for the node when it is deserialize()d.

Client Serializable types should call this one time from their serialize() method, after calling the parent class' serialize() method (if indeed that is called at all), passing it the name of their class, as it will be used by the classloader. By convention the class name is the same as it's C++ name, thus Serializable class foo::FooBar should call:

node.impl_class( "foo::FooBar" );
from it's serialize() function.

Historical note: the above call should be handled 100% transparently by this library. There are, however, legitimate use-cases which the template/macro-based solution cannot catch, so users are encouraged to set it manually, as described above. If you don't then you your serialized data will all have the same impl_class: probably that of the base-most Serializable class. That *will* break deserialization.

void s11n::data_node::insert const value_type  ) 
 

For compatibility with std::map.

Inserts a value_type (i.e., pair) into this object.

map_type& s11n::data_node::map  ) 
 

Returns the internally-used map_type (see the typedefs).

It is safe to modify this directly.

void s11n::data_node::name const std::string &  n  ) 
 

The name which should be used as the key for storing the node.

This is normally translated to something like an XML element name (e.g., <name>), and should not contain spaces or other characters which may not be usable as key names. To be safe, stick to alphanumeric and underscores, starting with a letter or underscore. (This class does no enforce any naming conventions, but your data file parsers certainly will.)

data_node& s11n::data_node::operator= const data_node rhs  ) 
 

See copy().

Does not throw.

mapped_type& s11n::data_node::operator[] const key_type key  ) 
 

Untested.

Returns a non-const reference to a property with the given key. If key does not exist a new entry is created.

const mapped_type s11n::data_node::operator[] const key_type key  )  const
 

std::string propval = node["bar"] is functionally identical to node.get_string("bar").

Unlike std::map and the like, calling this operator with a key which is not in the object does not create a new entry - it simply returns an empty string in that case. This behaviour is not a specific of the interface for purposes of data_node conventions.

void s11n::data_node::reset  )  [inline]
 

older name for clear().

Deprecated.

Definition at line 401 of file data_node.h.

References clear().

void s11n::data_node::set const char *  key,
const char *  val
[inline]
 

The <const char *> variants of get() and set() are to help the developer avoid having to cast so much and to help out compilers which have mediocre template support.

:/

Definition at line 585 of file data_node.h.

References set(), and set_string().

template<typename T>
void s11n::data_node::set const std::string &  key,
const T &  val
[inline]
 

See set_string().

This function is identical except that it converts val to string before saving it. If this type conversion is not possible it will fail at compile time. A value-conversion failure, on the other hand, is not caught at compile time.

Definition at line 568 of file data_node.h.

References set_string().

Referenced by set().

void s11n::data_node::set_bool const std::string &  key,
bool  val
 

set_bool() is provided to work around a potential compiler warning:

props.set( "foo", false );
// ambiguous: may be bool, const char *, char, or even int :/

void s11n::data_node::set_string const std::string &  key,
const std::string &  val
 

Sets the given key to the given value.

See get_string(): same notes apply here.

Referenced by set().


The documentation for this class was generated from the following file:
Generated on Tue Jul 20 10:46:48 2004 for s11n by doxygen 1.3.7