s11n::list Namespace Reference

The s11n::list namespace defines functors and algorithms for working with std::list/vector-style containers. More...


Classes

struct  serialize_list_f
 Functor equivalent of serialize_list(). More...
struct  deserialize_list_f
 Functor equivalent of deserialize_list(). More...
struct  serialize_streamable_list_f
 Functor equivalent of serialize_streamable_list(). More...
struct  deserialize_streamable_list_f
 Functor equivalent of deserialize_streamable_list(). More...
class  list_serializable_proxy
 list_serializable_proxy is a functor for de/serializing lists of Serializables. More...
class  streamable_list_serializable_proxy
 streamable_list_serializable_proxy is a functor for de/serializing lists of i/ostreamable Serializables (e.g., PODs). More...

Functions

template<typename NodeType, typename SerType>
bool serialize_list (NodeType &dest, const SerType &src)
 serialize_list() supports list/vector-like types containing any Serializable type.
template<typename NodeType, typename SerType>
bool serialize_list (NodeType &dest, const std::string &subnodename, const SerType &src)
 Identical to the two-argument form of serialize_list(), but serializes src into a subnode of dest, named subnodename.
template<typename NodeType, typename SerType>
bool deserialize_list (const NodeType &src, SerType &dest)
 For each [src.children().begin(),end()) an object of type SerType::value_type is created, deserialized, and is added to dest via push_back( item ).
template<typename NodeType, typename SerType>
bool deserialize_list (const NodeType &src, const std::string &subnodename, SerType &dest)
 Identical to the two-argument form of deserialize_list(), but deserializes a subnode of src, named subnodename.
template<typename NodeType, typename ListType>
bool serialize_streamable_list (NodeType &dest, const ListType &src)
 serialize_streamable_list serializes objects of type std::list<X> (and compatible list types, such as std::vector).
template<typename NodeType, typename ListType>
bool serialize_streamable_list (NodeType &dest, const std::string &subnodename, const ListType &src)
 Identical to serialize_streamable_list(dest,src), but creates a subnode in dest, named subnodename, where the data is stored.
template<typename NodeType, typename ListType>
bool deserialize_streamable_list (const NodeType &src, ListType &dest)
 Deserializes dest from src.
template<typename NodeType, typename ListType>
bool deserialize_streamable_list (const NodeType &src, const std::string &subnodename, ListType &dest)
 Identical to deserialize_streamable_list(), but looks for the data in a subnode of src named subnodename.


Detailed Description

The s11n::list namespace defines functors and algorithms for working with std::list/vector-style containers.

Function Documentation

template<typename NodeType, typename SerType>
bool s11n::list::deserialize_list ( const NodeType &  src,
const std::string &  subnodename,
SerType &  dest 
) [inline]

Identical to the two-argument form of deserialize_list(), but deserializes a subnode of src, named subnodename.

If no such child is found in src then false is returned.

template<typename NodeType, typename SerType>
bool s11n::list::deserialize_list ( const NodeType &  src,
SerType &  dest 
) [inline]

For each [src.children().begin(),end()) an object of type SerType::value_type is created, deserialized, and is added to dest via push_back( item ).

See serialize_list() for the list type requirements.

If SerType::value_type is a pointer type then dest owns any newly-created pointers, and it's owner (or the container itself) is responsible for cleaning them up. (Non-pointer types need no explicit clean-up, of course.)

SerType requirements:

dest must be empty upon calling this function, or its contents will be irrevocably lost when this function succeeds (which would lead to a leak if dest contained unmanaged pointers, even indirectly).

Returns true if all deserializations succeed. Stops processing and returns false at the first error, in which case dest is not modified: some children may or may not have been successfully deserialized, but we destroy them if deserialization of any fail. One immediate implication of this is that it will fail if src contains any other children than the type which dest expects. The s11n_traits::cleanup_functor is used to ensure that cleanup walks through any containers which hold pointers, deallocating them as well.

This function only throws if an underlying call to deserialize() or the classloader throws or if there is some sort of internal error (e.g., src contains child pointers which point to NULL).

Major behaviour change in 1.1.3+:

If this function throws or returns false then the target list is left untouched. See s11n::map::deserialize_map() for more information.

Referenced by s11n::list::list_serializable_proxy::operator()().

template<typename NodeType, typename ListType>
bool s11n::list::deserialize_streamable_list ( const NodeType &  src,
const std::string &  subnodename,
ListType &  dest 
) [inline]

Identical to deserialize_streamable_list(), but looks for the data in a subnode of src named subnodename.

Returns false if no child could be found.

ACHTUNG:

template<typename NodeType, typename ListType>
bool s11n::list::deserialize_streamable_list ( const NodeType &  src,
ListType &  dest 
) [inline]

Deserializes dest from src.

It reads in all properties from src, ignoring their keys and taking only their values. This is suitable for use with the result of a serialize_streamable_list() call. See that function for more information, including the conventions which must be supported by NodeType and ListType.

Always returns true - the bool return value is for API consistency.

ACHTUNG:

Referenced by s11n::plugin::path_finder_s11n::operator()(), and s11n::list::streamable_list_serializable_proxy::operator()().

template<typename NodeType, typename SerType>
bool s11n::list::serialize_list ( NodeType &  dest,
const std::string &  subnodename,
const SerType &  src 
) [inline]

Identical to the two-argument form of serialize_list(), but serializes src into a subnode of dest, named subnodename.

If serialization into dest child fails, the child node is not added to dest and the error (possibly an exception) is propagated back to the caller.

template<typename NodeType, typename SerType>
bool s11n::list::serialize_list ( NodeType &  dest,
const SerType &  src 
) [inline]

serialize_list() supports list/vector-like types containing any Serializable type.

Serializes (src.begin(),src.end()] to dest. Each item has a node name of that given to the ctor or an unspecified dummy value.

Returns true on success. If false is returned then dest is in an undefined state: some number of serializations may have succeeded before the failure. This operation stops processing at the first serialization error.

If serialization of a child fails, the child is not added to dest and any exception is propagated back to the caller.

Compatible ListTypes must support:

Restrictions on value_type's type:

Some s11n-side requirements:

If the underlying call to s11n::serialize() throws then the exception is propagated. If it throws, then dest is left in an undefined state, but no memory is leaked here because NodeType is responsible for cleaning up any of its children.

ACHTUNG: never pass the same destination container to this function more than once or you will get duplicate and/or incorrect data.

As of version 1.1.3, this function throws an s11n_exception if dest is not empty. The reason for this is to enforce that clients do not accidentally re-use the same (populated) node for serialization of multiple objects, which would cause deserialization of the container to fail.

Referenced by s11n::list::list_serializable_proxy::operator()().

template<typename NodeType, typename ListType>
bool s11n::list::serialize_streamable_list ( NodeType &  dest,
const std::string &  subnodename,
const ListType &  src 
) [inline]

Identical to serialize_streamable_list(dest,src), but creates a subnode in dest, named subnodename, where the data is stored.

ACHTUNG:

template<typename NodeType, typename ListType>
bool s11n::list::serialize_streamable_list ( NodeType &  dest,
const ListType &  src 
) [inline]

serialize_streamable_list serializes objects of type std::list<X> (and compatible list types, such as std::vector).

It stores them in such a way that they can be loaded into any compatible container via deserialize_streamable_list().

Conventions:

ACHTUNG:

Always returns true - the bool return value is for API consistency.

ACHTUNG 2:

Referenced by s11n::plugin::path_finder_s11n::operator()(), and s11n::list::streamable_list_serializable_proxy::operator()().


Generated on Sun Apr 27 13:16:05 2008 for libs11n by  doxygen 1.5.3