00001 //////////////////////////////////////////////////////////////////////// 00002 // 00003 //////////////////////////////////////////////////////////////////////// 00004 #ifndef s11n_net_s11n_v1_1_LIST_HPP_INCLUDED 00005 #define s11n_net_s11n_v1_1_LIST_HPP_INCLUDED 1 00006 00007 00008 namespace s11n { 00009 00010 00011 /** 00012 The s11n::list namespace defines functors and algorithms for 00013 working with std::list/vector-style containers. 00014 */ 00015 namespace list { 00016 00017 /** 00018 serialize_list() supports list/vector-like types containing 00019 any Serializable type. Serializes (src.begin(),src.end()] 00020 to dest. Each item has a node name of that given to the 00021 ctor or an unspecified dummy value. 00022 00023 Returns true on success. If false is returned then dest is 00024 in an undefined state: some number of serializations may 00025 have succeeded before the failure. This operation stops 00026 processing at the first serialization error. 00027 00028 If serialization of a child fails, the child is not 00029 added to dest and any exception is propagated back 00030 to the caller. 00031 00032 Compatible ListTypes must support: 00033 00034 - a value_type typedef describing the type of it's contents. 00035 00036 - push_back( value_type ) 00037 00038 - const_iterator typedefs. 00039 00040 Restrictions on value_type's type: 00041 00042 - Must be a Serializable. This includes any i/o streamable 00043 type which has a proxy installed by s11n (includes all PODs 00044 and std::string by default). 00045 00046 - May be a pointer type. NodeType must not be a pointer. 00047 00048 Some s11n-side requirements: 00049 00050 - ListType must be registered with the ListType classloader. 00051 00052 If the underlying call to ::s11n::serialize() 00053 throws then the exception is propagated. If it 00054 throws, then dest is left in an undefined state, 00055 but no memory is leaked here because NodeType is 00056 responsible for cleaning up any of its children. 00057 00058 ACHTUNG: never pass the same destination container to 00059 this function more than once or you will get duplicate and/or 00060 incorrect data. 00061 00062 As of version 1.1.3, this function throws an s11n_exception 00063 if dest is not empty. The reason for this is to enforce 00064 that clients do not accidentally re-use the same (populated) 00065 node for serialization of multiple objects, which would cause 00066 deserialization of the container to fail. 00067 */ 00068 template <typename NodeType, typename SerType> 00069 bool serialize_list( NodeType & dest, const SerType & src ); 00070 00071 00072 00073 /** 00074 Identical to the two-argument form of serialize_list(), but 00075 serializes src into a subnode of dest, named subnodename. 00076 00077 If serialization into dest child fails, the child 00078 node is not added to dest and the error (possibly 00079 an exception) is propagated back to the caller. 00080 */ 00081 template <typename NodeType, typename SerType> 00082 bool serialize_list( NodeType & dest, const std::string & subnodename, const SerType & src ); 00083 00084 00085 /** 00086 Functor equivalent of serialize_list(). 00087 00088 Added in version 1.1.3. 00089 */ 00090 struct serialize_list_f : ::s11n::serialize_binary_f_tag 00091 { 00092 template <typename NodeType, typename SerType> 00093 inline bool operator()( NodeType & dest, const SerType & src ) const 00094 { 00095 return serialize_list<NodeType,SerType>( dest, src ); 00096 } 00097 00098 template <typename NodeType, typename SerType> 00099 inline bool operator()( NodeType & dest, const std::string & subnodename, const SerType & src ) const 00100 { 00101 return serialize_list<NodeType,SerType>( dest, src ); 00102 } 00103 }; 00104 00105 00106 /** 00107 For each [src.children().begin(),end()) an object 00108 of type SerType::value_type is created, deserialized, 00109 and is added to dest via push_back( item ). 00110 00111 See serialize_list() for the list type requirements. 00112 00113 If SerType::value_type is a pointer type then dest owns any 00114 newly-created pointers, and it's owner (or the container 00115 itself) is responsible for cleaning them up. (Non-pointer 00116 types need no explicit clean-up, of course.) 00117 00118 SerType requirements: 00119 00120 - Must be a Serializable type, as must contained type(s). 00121 00122 - May not be a pointer type, but may contain pointer types. 00123 00124 - A working s11n_traits<SerType>::cleanup_functor must be 00125 installed which properly frees up list entries. 00126 00127 - Must have a swap() member function, to support the 00128 no-change-on-error policy. 00129 00130 dest must be empty upon calling this function, or 00131 its contents will be irrevocably lost when this 00132 function succeeds (which would lead to a leak if 00133 dest contained unmanaged pointers, even 00134 indirectly). 00135 00136 00137 Returns true if all deserializations succeed. 00138 Stops processing and returns false at the first 00139 error, in which case dest is not modified: some 00140 children may or may not have been successfully 00141 deserialized, but we destroy them if 00142 deserialization of any fail. One immediate 00143 implication of this is that it will fail if src 00144 contains any other children than the type which 00145 dest expects. The s11n_traits::cleanup_functor 00146 is used to ensure that cleanup walks through 00147 any containers which hold pointers, deallocating 00148 them as well. 00149 00150 This function only throws if an underlying call to 00151 deserialize() or the classloader throws or if there 00152 is some sort of internal error (e.g., src contains 00153 child pointers which point to NULL). 00154 00155 Major behaviour change in 1.1.3+: 00156 00157 If this function throws or returns false then the 00158 target list is left untouched. See 00159 ::s11n::map::deserialize_map() for more 00160 information. 00161 */ 00162 template <typename NodeType, typename SerType> 00163 bool deserialize_list( const NodeType & src, SerType & dest ); 00164 00165 00166 00167 /** 00168 Identical to the two-argument form of deserialize_list(), but 00169 deserializes a subnode of src, named subnodename. If no such 00170 child is found in src then false is returned. 00171 */ 00172 template <typename NodeType, typename SerType> 00173 bool deserialize_list( const NodeType & src, const std::string & subnodename, SerType & dest ); 00174 00175 00176 /** 00177 Functor equivalent of deserialize_list(). 00178 00179 Added in version 1.1.3. 00180 */ 00181 struct deserialize_list_f : ::s11n::deserialize_binary_f_tag 00182 { 00183 00184 template <typename NodeType, typename SerType> 00185 inline bool operator()( const NodeType & src, SerType & dest ) const 00186 { 00187 return deserialize_list<NodeType,SerType>( src, dest ); 00188 } 00189 00190 template <typename NodeType, typename SerType> 00191 inline bool operator()( const NodeType & src, const std::string & subnodename, SerType & dest ) const 00192 { 00193 return deserialize_list<NodeType,SerType>( src, dest ); 00194 } 00195 }; 00196 00197 00198 /** 00199 serialize_streamable_list serializes objects of type 00200 <tt>std::list<X></tt> (and compatible list types, 00201 such as std::vector). It stores them in such a way that 00202 they can be loaded into any compatible container via 00203 deserialize_streamable_list(). 00204 00205 Conventions: 00206 00207 - NodeType must support a generic set(Key,Val) function, as 00208 implemented by the s11n::data_node interface. 00209 00210 - ListType must conform to std::list conventions and it's 00211 value_type must be a non-pointer type which is 00212 i/ostreamable (this includes all PODs and 00213 std::string). Pointers are not supported by 00214 this function. 00215 00216 ACHTUNG: 00217 00218 - Never call this on a node for which you store other 00219 properties, as deserialize_streamable_list() will consume them 00220 if you use that function. 00221 00222 - This function sets dummy property keys, both to please 00223 the conventions of keys having non-empty values and to keep 00224 the list in the proper order. It uses keys which should be 00225 portable to, e.g., standard XML. 00226 00227 Always returns true - the bool return value is for API consistency. 00228 00229 ACHTUNG 2: 00230 00231 - The return type of this function was changed from size_t 00232 to bool in version 0.9.10. 00233 */ 00234 template <typename NodeType, typename ListType> 00235 bool serialize_streamable_list( NodeType & dest, const ListType & src ); 00236 00237 00238 /** 00239 Identical to serialize_streamable_list(dest,src), but 00240 creates a subnode in dest, named subnodename, where the 00241 data is stored. 00242 00243 ACHTUNG: 00244 00245 - The return type of this function was changed from size_t 00246 to bool in version 0.9.10. 00247 */ 00248 template <typename NodeType, typename ListType> 00249 bool serialize_streamable_list( NodeType & dest, const std::string & subnodename, const ListType & src ); 00250 00251 00252 /** 00253 Functor equivalent of serialize_streamable_list(). 00254 00255 Added in version 1.1.3. 00256 */ 00257 struct serialize_streamable_list_f : ::s11n::serialize_binary_f_tag 00258 { 00259 template <typename NodeType, typename ListType> 00260 inline bool operator()( NodeType & dest, const ListType & src ) const 00261 { 00262 return serialize_streamable_list<NodeType,ListType>( dest, src ); 00263 } 00264 00265 template <typename NodeType, typename ListType> 00266 inline bool operator()( NodeType & dest, const std::string & subnodename, const ListType & src ) const 00267 { 00268 return serialize_streamable_list<NodeType,ListType>( dest, src ); 00269 } 00270 }; 00271 00272 00273 /** 00274 Deserializes dest from src. It reads in all properties from 00275 src, ignoring their keys and taking only their values. This 00276 is suitable for use with the result of a 00277 serialize_streamable_list() call. See that function for more 00278 information, including the conventions which must be 00279 supported by NodeType and ListType. 00280 00281 Always returns true - the bool return value is for API consistency. 00282 00283 ACHTUNG: 00284 00285 - The return type of this function was changed from size_t 00286 to bool in version 0.9.10. 00287 00288 */ 00289 template <typename NodeType, typename ListType> 00290 bool deserialize_streamable_list( const NodeType & src, ListType & dest ); 00291 00292 00293 00294 /** 00295 Identical to deserialize_streamable_list(), but looks for 00296 the data in a subnode of src named subnodename. 00297 00298 Returns false if no child could be found. 00299 00300 ACHTUNG: 00301 00302 - The return type of this function was changed from size_t 00303 to bool in version 0.9.10. 00304 00305 */ 00306 template <typename NodeType, typename ListType> 00307 bool deserialize_streamable_list( const NodeType & src, const std::string & subnodename, ListType & dest ); 00308 00309 00310 00311 00312 00313 /** 00314 Functor equivalent of deserialize_streamable_list(). 00315 00316 Added in version 1.1.3. 00317 */ 00318 struct deserialize_streamable_list_f : ::s11n::deserialize_binary_f_tag 00319 { 00320 template <typename NodeType, typename ListType> 00321 inline bool operator()( const NodeType & src, const std::string & subnodename, ListType & dest ) const 00322 { 00323 return deserialize_streamable_list<NodeType,ListType>( src, dest ); 00324 } 00325 00326 template <typename NodeType, typename ListType> 00327 inline bool operator()( const NodeType & src, ListType & dest ) const 00328 { 00329 return deserialize_streamable_list<NodeType,ListType>( src, dest ); 00330 } 00331 }; 00332 00333 00334 /** 00335 list_serializable_proxy is a functor for de/serializing lists 00336 of Serializables. 00337 */ 00338 class list_serializable_proxy : ::s11n::serialize_binary_f_tag, 00339 ::s11n::deserialize_binary_f_tag 00340 { 00341 public: 00342 list_serializable_proxy() 00343 {} 00344 00345 /** 00346 see serialize_list(). 00347 00348 */ 00349 template <typename NodeType, typename SerType> 00350 inline bool operator()( NodeType & dest, const SerType & src ) const 00351 { 00352 return serialize_list( dest, src ); 00353 } 00354 00355 /** see deserialize_list(). */ 00356 template <typename NodeType, typename SerType> 00357 inline bool operator()( const NodeType & src, SerType & dest ) const 00358 { 00359 return deserialize_list( src, dest ); 00360 } 00361 }; 00362 00363 /** 00364 streamable_list_serializable_proxy is a functor for de/serializing lists 00365 of i/ostreamable Serializables (e.g., PODs). 00366 */ 00367 class streamable_list_serializable_proxy : ::s11n::serialize_binary_f_tag, 00368 ::s11n::deserialize_binary_f_tag 00369 { 00370 public: 00371 streamable_list_serializable_proxy() 00372 {} 00373 00374 /** 00375 see serialize_streamable_list(). 00376 00377 */ 00378 template <typename NodeType, typename SerType> 00379 inline bool operator()( NodeType & dest, const SerType & src ) const 00380 { 00381 return serialize_streamable_list( dest, src ); 00382 } 00383 00384 /** see deserialize_streamable_list(). */ 00385 template <typename NodeType, typename SerType> 00386 inline bool operator()( const NodeType & src, SerType & dest ) const 00387 { 00388 return deserialize_streamable_list( src, dest ); 00389 } 00390 }; 00391 00392 00393 00394 } // namespace list 00395 } // namespace s11n 00396 00397 #include <s11n.net/s11n/proxy/listish.tpp> // implementations 00398 00399 #endif // s11n_net_s11n_v1_1_LIST_HPP_INCLUDED