mail[Wesnoth-commits] r20402 - in /trunk/src/serialization: binary_wml.cpp binary_wml.hpp


Others Months | Index by Date | Thread Index
>>   [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Header


Content

Posted by gurt on September 15, 2007 - 16:01:
Author: hajo
Date: Sat Sep 15 16:01:10 2007
New Revision: 20402

URL: http://svn.gna.org/viewcvs/wesnoth?rev=20402&view=rev
Log:
doxygen, comments

Modified:
    trunk/src/serialization/binary_wml.cpp
    trunk/src/serialization/binary_wml.hpp

Modified: trunk/src/serialization/binary_wml.cpp
URL: 
http://svn.gna.org/viewcvs/wesnoth/trunk/src/serialization/binary_wml.cpp?rev=20402&r1=20401&r2=20402&view=diff
==============================================================================
--- trunk/src/serialization/binary_wml.cpp (original)
+++ trunk/src/serialization/binary_wml.cpp Sat Sep 15 16:01:10 2007
@@ -13,6 +13,9 @@
    See the COPYING file for more details.
 */
 
+//! @file serialization/binary_wml.cpp 
+//! Data compression, designed for network traffic.
+
 #include "global.hpp"
 
 #include "config.hpp"
@@ -26,33 +29,34 @@
 
 #define ERR_CF LOG_STREAM(err, config)
 
-//data compression. Compression is designed for network traffic.
-//assumptions compression is based on:
+// Data compression. Compression is designed for network traffic.
+// Assumptions the compression is based on:
 // - most space is taken up by element names and attribute names
-// - there are relatively few element names and attribute names that are 
repeated many times
+// - there are relatively few element names and attribute names 
+//   that are repeated many times
 //
-//how it works: there are some control characters:
+// How it works: there are some control characters:
 // 'compress_open_element': signals that the next word found is an element.
-// any words found that are not after this are assumed to be attributes
-// 'compress_close_element': signals to close the current element
-// 'compress_schema_item': signals that following is a nul-delimited string, 
which should
-//                         be added as a word in the schema
+// Any words found that are not after this are assumed to be attributes:
+// 'compress_close_element': signals to close the current element.
+// 'compress_schema_item': signals that following is a nul-delimited string, 
+//                         which should be added as a word in the schema.
 // 'compress_literal_word': signals that following is a word stored as a 
nul-delimited string
-//    (an attribute name, unless it was preceeded by 'compress_open_element')
+//    (an attribute name, unless it was preceeded by 
'compress_open_element').
 //
-// all other characters are mapped to words. When an item is inserted into 
the schema,
+// All other characters are mapped to words. When an item is inserted into 
the schema,
 // it is mapped to the first available character. Any attribute found is 
always followed
 // by a nul-delimited string which is the value for the attribute.
 //
-// the schema objects are designed to be persisted. That is, in a network 
game, both peers
-// can store their schema objects, and so rather than sending schema data 
each time, the peers
-// use and build their schemas as the game progresses, adding a new word to 
the schema anytime
-// it is required.
+// The schema objects are designed to be persisted. That is, in a network 
game, 
+// both peers can store their schema objects, and so rather than sending 
+// schema data each time, the peers use and build their schemas as the 
+// game progresses, adding a new word to the schema anytime it is required.
 
 static const unsigned int
        compress_open_element = 0, compress_close_element = 1,
-       compress_schema_item = 2, compress_literal_word = 3,
-       compress_first_word = 4, compress_end_words = 256;
+       compress_schema_item  = 2, compress_literal_word = 3,
+       compress_first_word   = 4, compress_end_words = 256;
 static const size_t compress_max_words = compress_end_words - 
compress_first_word;
 static const size_t max_schema_item_length = 20;
 static const int max_recursion_levels = 1000;
@@ -80,34 +84,34 @@
        if (word.size() > max_schema_item_length)
                return schema.word_to_char.end();
 
-       //see if this word is already in the schema
+       // See if this word is already in the schema
        const compression_schema::word_char_map::const_iterator w = 
schema.word_to_char.find(word);
        if (w != schema.word_to_char.end()) {
-               //in the schema. Return it
+               // It is in the schema. Return it.
                return w;
        } else if (schema.word_to_char.size() < compress_max_words) {
-               //we can add the word to the schema
-
-               //we insert the code to add a schema item, followed by the 
zero-delimited word
+               // We can add the word to the schema
+
+               // We insert the code to add a schema item, followed by the 
zero-delimited word.
                out.put(compress_schema_item);
                compress_output_literal_word(out, word);
 
                return add_word_to_schema(word, schema);
        } else {
-               //it's not there, and there's no room to add it
+               // It is not there, and there is no room to add it
                return schema.word_to_char.end();
        }
 }
 
 static void compress_emit_word(std::ostream &out, std::string const &word, 
compression_schema &schema)
 {
-       //get the word in the schema
+       // Get the word in the schema
        const compression_schema::word_char_map::const_iterator w = 
get_word_in_schema(word, schema, out);
        if (w != schema.word_to_char.end()) {
-               //the word is in the schema, all we have to do is output the 
compression code for it.
+               // The word is in the schema, all we have to do is output the 
compression code for it.
                out.put(w->second);
        } else {
-               //the word is not in the schema. Output it as a literal word
+               // The word is not in the schema. Output it as a literal word.
                out.put(compress_literal_word);
                compress_output_literal_word(out, word);
        }
@@ -129,10 +133,10 @@
 
        for (string_map::const_iterator i = cfg.values.begin(), i_end = 
cfg.values.end(); i != i_end; ++i) {
                if (i->second.empty() == false) {
-                       //output the name, using compression
+                       // Output the name, using compression
                        compress_emit_word(out, i->first, schema);
 
-                       //output the value, with no compression
+                       // Output the value, with no compression
                        compress_output_literal_word(out, 
i->second.to_serialized());
                }
        }
@@ -197,14 +201,14 @@
                                config &cfg2 = cfg.add_child(word);
                                read_compressed_internal(cfg2, in, schema, 
level + 1);
                        } else {
-                               //we have a name/value pair, the value is 
always a literal string
+                               // We have a name/value pair, the value is 
always a literal string
                                std::string value = 
compress_read_literal_word(in);
                                t_string t_value = 
t_string::from_serialized(value);
                                cfg.values.insert(std::make_pair(word, 
t_value));
                        }
                }
 
-               } //end switch
+               } // end switch
        }
 }
 
@@ -223,3 +227,4 @@
        compression_schema schema;
        read_compressed(cfg, in, schema);
 }
+

Modified: trunk/src/serialization/binary_wml.hpp
URL: 
http://svn.gna.org/viewcvs/wesnoth/trunk/src/serialization/binary_wml.hpp?rev=20402&r1=20401&r2=20402&view=diff
==============================================================================
--- trunk/src/serialization/binary_wml.hpp (original)
+++ trunk/src/serialization/binary_wml.hpp Sat Sep 15 16:01:10 2007
@@ -12,6 +12,8 @@
 
    See the COPYING file for more details.
 */
+
+
 #ifndef SERIALIZATION_BINARY_WML_HPP_INCLUDED
 #define SERIALIZATION_BINARY_WML_HPP_INCLUDED
 
@@ -21,7 +23,7 @@
 
 class config;
 
-//this object holds the schema by which config objects can be compressed and 
decompressed.
+//! Holds the schema by which config objects can be compressed and 
decompressed.
 struct compression_schema
 {
        compression_schema() : char_to_word(), word_to_char() { }
@@ -33,12 +35,15 @@
        word_char_map word_to_char;
 };
 
-//functions to read and write compressed data. The schema will be created 
and written
-//with the data. However if you are making successive writes (e.g. a network 
connection)
-//you can re-use the same schema on the sending end, and the receiver can 
store the schema,
-//meaning that the entire schema won't have to be transmitted each time.
+//  Read and write compressed data. 
 
+//! Write compressed data. 
+//! The schema will be created and written with the data. 
+//! However if you are making successive writes (e.g. a network connection),
+//! you can re-use the same schema on the sending end, and the receiver can 
store 
+//! the schema, meaning that the entire schema won't have to be transmitted 
each time.
 void write_compressed(std::ostream &out, config const &cfg, 
compression_schema &schema);
+//! Read compressed data. 
 void read_compressed(config &cfg, std::istream &in, compression_schema 
&schema); //throws config::error
 
 void write_compressed(std::ostream &out, config const &cfg);




Related Messages


Powered by MHonArc, Updated Sat Sep 15 16:20:29 2007