Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

s11nlite.hpp File Reference

#include <memory>
#include <iterator>
#include <s11n.net/s11n/s11n.hpp>
#include <s11n.net/s11n/io/data_node_io.hpp>
#include <s11n.net/s11n/client_api.hpp>

Go to the source code of this file.

Namespaces

namespace  s11nlite

Defines

#define S11N_LITE_H_INCLUDED   1
#define s11n_S11NLITE_INCLUDED   1

Typedefs

typedef client_api< s11n::s11n_nodeclient_interface
typedef client_interface::node_type node_type
 node_type is the type used to store/load a Serializable object's data.
typedef client_interface::node_traits node_traits
 The s11n::node_traits type for node_type.
typedef client_interface::serializer_interface serializer_interface
 This is the base-most type of the serializers used by s11nlite.

Functions

client_interfaceinstance ()
 Returns the client_interface object used by the s11nlite API.
void instance (client_interface *newinstance)
 Sets the client_interface object used by the s11nlite API.
serializer_interfacecreate_serializer ()
 Returns a new instance of the default serializer class.
serializer_interfacecreate_serializer (const std::string &classname)
 Returns a new instance of the given serializer class, or 0 if one could not be loaded.
void serializer_class (const std::string &)
 Sets the current Serializer class used by s11nlite's create_serializer().
std::string serializer_class ()
 Gets the name of the current Serializer type.
node_typefind_child (node_type &parent, const std::string subnodename)
 A non-const overload.
const node_typefind_child (const node_type &parent, const std::string subnodename)
 Equivalent to s11n::find_child_by_name( parent, subnodename ).
template<typename SerializableType>
bool serialize (node_type &dest, const SerializableType &src)
 See s11n::serialize().
template<typename SerializableType>
bool serialize_subnode (node_type &dest, const std::string &subnodename, const SerializableType &src)
 See s11n::serialize().
bool save (const node_type &src, std::ostream &dest)
 Saves the given node to the given ostream using the default serializer type.
bool save (const node_type &src, const std::string &filename)
 Saves the given node to the given filename using the default serializer type.
template<typename SerializableType>
bool save (const SerializableType &src, std::ostream &dest)
 Saves the given Serializable to the given ostream using the default serializer type.
template<typename SerializableType>
bool save (const SerializableType &src, const std::string &dest)
 Saves the given Serializable to the given filename using the default serializer type.
node_typeload_node (const std::string &src)
 Tries to load a node from the given filename.
node_typeload_node (std::istream &src)
 Tries to load a node from the given input stream.
template<typename SerializableType>
SerializableType * deserialize (const node_type &src)
 See s11n::deserialize().
template<typename DeserializableT>
bool deserialize (const node_type &src, DeserializableT &target)
 Tries to deserialize src into target.
template<typename DeserializableT>
bool deserialize_subnode (const node_type &src, const std::string &subnodename, DeserializableT &target)
 Exactly like deserialize(), but operates on a subnode of src named subnodename.
template<typename DeserializableT>
DeserializableT * deserialize_subnode (const node_type &src, const std::string &subnodename)
 Exactly like deserialize(), but operates on a subnode of src named subnodename.
template<typename SerializableType>
SerializableType * load_serializable (std::istream &src)
 Tries to load a data_node from src, then deserialize that to a SerializableType.
template<typename SerializableType>
SerializableType * load_serializable (const std::string &src)
 Overloaded form which takes a file name.
template<typename SerializableType>
SerializableType * s11n_clone (const SerializableType &tocp)
 Clones an arbitrary SerializableType using its DataNodeType serialization implementation.
template<typename Type1, typename Type2>
bool s11n_cast (const Type1 &t1, Type2 &t2)
 "Casts" t1 to t2 using serialization.
template<typename SerT>
save_serializable_string_nullary_f<
SerT > 
save_nullary_f (SerT const &src, std::string const &dest)
 Returns save_serializable_string_nullary_f<SerT>( src, dest ).
template<typename SerT>
save_serializable_stream_nullary_f<
SerT > 
save_nullary_f (SerT const &src, std::ostream &dest)
 Returns save_serializable_stream_nullary_f<SerT>( src, dest ).
save_node_string_nullary_f save_nullary_f (node_type const &src, std::string const &dest)
 Returns save_node_string_nullary_f( src, dest ).
save_node_stream_nullary_f save_nullary_f (node_type const &src, std::ostream &dest)
 Returns save_node_stream_nullary_f( src, dest ).
load_node_nullary_string_f load_node_nullary_f (std::string const &s)
 Returns load_node_nullary_string_f(s).
load_node_stream_nullary_f load_node_nullary_f (std::istream &s)
 Returns load_node_stream_nullary_f(s).


Define Documentation

#define S11N_LITE_H_INCLUDED   1
 

Definition at line 2 of file s11nlite.hpp.

#define s11n_S11NLITE_INCLUDED   1
 

Definition at line 7 of file s11nlite.hpp.


Typedef Documentation

typedef client_api<s11n::s11n_node> s11nlite::client_interface
 

Definition at line 71 of file s11nlite.hpp.

typedef client_interface::node_traits s11nlite::node_traits
 

The s11n::node_traits type for node_type.

Definition at line 88 of file s11nlite.hpp.

typedef client_interface::node_type s11nlite::node_type
 

node_type is the type used to store/load a Serializable object's data.

FYI: node_type might change to s11n::s11n_node in 1.1, because that implementation is a tiny bit more lightweight than s11n::data_node, and was designed specifically with node_traits in mind (data_node came much earlier than either of them). If you only use node_traits to access nodes' data then your code will be oblivious to this change (but will need a recompile).

Definition at line 85 of file s11nlite.hpp.

typedef client_interface::serializer_interface s11nlite::serializer_interface
 

This is the base-most type of the serializers used by s11nlite.

Definition at line 93 of file s11nlite.hpp.


Function Documentation

serializer_interface* create_serializer const std::string &  classname  ) 
 

Returns a new instance of the given serializer class, or 0 if one could not be loaded.

e.g., register_serializer() will do the trick.

If no serializer for classname is found and classname does not contain the string "_serializer", then then (classname+"_serializer") is tried. This is intended to ease DLL lookups for the conventional abbreviations for the Serializer classes (i.e., my_serializer).

The caller owns the returned pointer, which may be 0.

Definition at line 158 of file serializers.hpp.

serializer_interface* create_serializer  ) 
 

Returns a new instance of the default serializer class.

The caller owns the returned pointer.

template<typename DeserializableT>
bool deserialize const node_type src,
DeserializableT &  target
 

Tries to deserialize src into target.

Returns true on success. If false is returned then target is not guaranteed to be in a useful state: this depends entirely on the object (but, it could be argued, it it was in a useful state its deserialize operator would have returned true!).

Definition at line 325 of file s11nlite.hpp.

References s11nlite::instance().

template<typename SerializableType>
SerializableType* deserialize const node_type src  ) 
 

See s11n::deserialize().

ACHTUNG: if you are using both s11n and s11nlite namespaces this function will be ambiguous with one provided in the namespace s11n. You must then qualify it with the namespace of the one you wish to use.

Definition at line 310 of file s11nlite.hpp.

References s11nlite::instance().

Referenced by s11n::io::funxml_serializer< NodeType >::deserialize(), and s11n::io::tree_builder_lexer< NodeType, sharing::simplexml_sharing_context >::deserialize().

template<typename DeserializableT>
DeserializableT* deserialize_subnode const node_type src,
const std::string &  subnodename
 

Exactly like deserialize(), but operates on a subnode of src named subnodename.

Returns 0 if no such file is found.

Definition at line 350 of file s11nlite.hpp.

References s11nlite::instance().

template<typename DeserializableT>
bool deserialize_subnode const node_type src,
const std::string &  subnodename,
DeserializableT &  target
 

Exactly like deserialize(), but operates on a subnode of src named subnodename.

Returns false if no such file is found.

Definition at line 337 of file s11nlite.hpp.

References s11nlite::instance().

const node_type* find_child const node_type parent,
const std::string  subnodename
 

Equivalent to s11n::find_child_by_name( parent, subnodename ).

node_type* find_child node_type parent,
const std::string  subnodename
 

A non-const overload.

Ownership is not modified by calling this function: normally the parent node owns it.

void instance client_interface newinstance  ) 
 

Sets the client_interface object used by the s11nlite API.

Ownership of newinstance IS NOT transfered. Passing NULL will cause it to revert to the default instance. newinstance must live as long as any client is using s11nlite, and when newinstance is destroyed, 0 must be passed to this function to disassociate the object from the library.

client_interface& instance  ) 
 

Returns the client_interface object used by the s11nlite API.

There is guaranteed to return *some* object, except possibly post-main() (where all bets are off).

See instance(client_interface*) for more details.

Referenced by s11n::fac::factory_mgr< InterfaceT, KeyType >::aliases(), s11nlite::deserialize(), s11nlite::deserialize_subnode(), s11n::io::data_node_serializer< NodeType >::entity_translations(), s11n::fac::factory_mgr< InterfaceT, KeyType >::factory_map(), s11n::fac::factory_mgr< InterfaceT, KeyType >::instance(), s11nlite::load_serializable(), s11n::cl::object_factory< InterfaceBase >::operator()(), s11nlite::client_api< NodeType >::provides_serializer(), s11n::s11n_cast(), s11n::s11n_clone(), s11nlite::save(), s11nlite::serialize(), and s11nlite::serialize_subnode().

node_type* load_node std::istream &  is  ) 
 

Tries to load a node from the given input stream.

ACHTUNG: Only usable for loading ROOT nodes.

Definition at line 393 of file data_node_io.hpp.

node_type* load_node const std::string &  src  ) 
 

Tries to load a node from the given filename.

The caller owns the returned pointer.

Referenced by s11nlite::simple_config::simple_config().

load_node_stream_nullary_f load_node_nullary_f std::istream &  s  )  [inline]
 

Returns load_node_stream_nullary_f(s).

Definition at line 770 of file s11nlite.hpp.

load_node_nullary_string_f load_node_nullary_f std::string const &  s  )  [inline]
 

Returns load_node_nullary_string_f(s).

Definition at line 761 of file s11nlite.hpp.

template<typename SerializableType>
SerializableType* load_serializable const std::string &  src  ) 
 

Overloaded form which takes a file name.

1.1.3: removed the never-used 2nd parameter.

Definition at line 373 of file s11nlite.hpp.

References s11nlite::instance().

template<typename SerializableType>
SerializableType* load_serializable std::istream &  src  ) 
 

Tries to load a data_node from src, then deserialize that to a SerializableType.

Definition at line 362 of file s11nlite.hpp.

References s11nlite::instance().

template<typename Type1, typename Type2>
bool s11n_cast const Type1 &  t1,
Type2 &  t2
 

"Casts" t1 to t2 using serialization.

This will work whenever t1 and t2 are "semantically compatible", whatever that really means. It can be used, e.g., to copy a list<int> to a vector<double>, provided both types have been proxied. In practice, this means: if Type1 and Type2 both use the same, or compatible, de/ser algorithms, they are s11n_cast-able to one another.

Note that in the case of containers, the pointerness of the contained types is irrelevant: this works on both, thus a list<int> can be "cast" to a vector<double*>.

As usual for a failed deserialization, if it returns false then t2 may be in an undefined state. There is no guaranty, however, that t2's deserialize operator will ever be called, as the serialization of t1 must first succeed for that to happen.

Type2 may not currently be a pointer type, but Type1 may be. This will be fixed someday (when someone complains).

Exceptions and errors:

On error this function will return false or propagate an exception, as dictated by serialize() and then deserialize() (in that order).

If Type1 and Type2 are not guaranteed to be monomorphic or base-most Serializable types, then it is good practice to explicitely specify them as templatized parameters, and not rely on implicit type selection, which might choose the wrong type (not the base-most one, which is what s11n is "keyed" to), which will mean that s11n "can't find" the registration code for the type.

Definition at line 393 of file s11nlite.hpp.

References s11nlite::instance().

template<typename SerializableType>
SerializableType* s11n_clone const SerializableType &  tocp  ) 
 

Clones an arbitrary SerializableType using its DataNodeType serialization implementation.

This function was renamed from clone() in version 1.1.

Definition at line 384 of file s11nlite.hpp.

References s11nlite::instance().

template<typename SerializableType>
bool save const SerializableType &  src,
const std::string &  dest
 

Saves the given Serializable to the given filename using the default serializer type.

Returns true on success, false on error.

ONLY use this for saving root nodes!

Definition at line 253 of file s11nlite.hpp.

References s11nlite::instance().

template<typename SerializableType>
bool save const SerializableType &  src,
std::ostream &  dest
 

Saves the given Serializable to the given ostream using the default serializer type.

Returns true on success, false on error.

ONLY use this for saving root nodes!

Definition at line 240 of file s11nlite.hpp.

References s11nlite::instance().

bool save const node_type src,
const std::string &  filename
 

Saves the given node to the given filename using the default serializer type.

Returns true on success, false on error.

ONLY use this for saving root nodes!

bool save const node_type src,
std::ostream &  dest
 

Saves the given node to the given ostream using the default serializer type.

Returns true on success, false on error.

ONLY use this for saving root nodes!

Referenced by s11nlite::save_nullary_base_f< ::s11nlite::node_type, std::ostream & >::operator()(), s11nlite::save_stream_unary_f::operator()(), s11nlite::save_string_unary_f::operator()(), s11nlite::save_binary_f::operator()(), and s11nlite::simple_config::~simple_config().

save_node_stream_nullary_f save_nullary_f node_type const &  src,
std::ostream &  dest
[inline]
 

Returns save_node_stream_nullary_f( src, dest ).

Definition at line 691 of file s11nlite.hpp.

save_node_string_nullary_f save_nullary_f node_type const &  src,
std::string const &  dest
[inline]
 

Returns save_node_string_nullary_f( src, dest ).

Definition at line 683 of file s11nlite.hpp.

template<typename SerT>
save_serializable_stream_nullary_f<SerT> save_nullary_f SerT const &  src,
std::ostream &  dest
[inline]
 

Returns save_serializable_stream_nullary_f<SerT>( src, dest ).

Definition at line 674 of file s11nlite.hpp.

template<typename SerT>
save_serializable_string_nullary_f<SerT> save_nullary_f SerT const &  src,
std::string const &  dest
[inline]
 

Returns save_serializable_string_nullary_f<SerT>( src, dest ).

Definition at line 664 of file s11nlite.hpp.

template<typename SerializableType>
bool serialize node_type dest,
const SerializableType &  src
 

See s11n::serialize().

Definition at line 193 of file s11nlite.hpp.

References s11nlite::instance().

template<typename SerializableType>
bool serialize_subnode node_type dest,
const std::string &  subnodename,
const SerializableType &  src
 

See s11n::serialize().

Definition at line 203 of file s11nlite.hpp.

References s11nlite::instance().

std::string serializer_class  ) 
 

Gets the name of the current Serializer type.

void serializer_class const std::string &   ) 
 

Sets the current Serializer class used by s11nlite's create_serializer().

Pass it a class name, or one of the convenience names listed in create_serializer(string).


Generated on Thu Sep 29 20:01:15 2005 for libs11n-1.1.3-dev by  doxygen 1.4.1