Added reset function for StringCodec::Decoder

[libs/core.git] / source / codec.h

diff --git a/source/codec.h b/source/codec.h
index 8ea99915c2451fc161fc53d16e482ebef77a28a7..5fb29db29b305577582e6ed56c58f3bda61d823c 100644 (file)
--- a/source/codec.h
+++ b/source/codec.h
@@ -17,12 +17,13 @@ public:
 };
 
 /**
-Base class for string codecs.  Mostly abstract.  Use one of the derived classes
-or the function create_codec to create a specific codec.
+Base class for string codecs.  Use one of the derived classes or the function
+create_codec to create a specific codec.
 
 For the purposes of this class, an std::wstring is considered to contain
 Unicode characters and an std::string is considered to be an encoded sequence
-of bytes.  Codecs are able to determine if an encoded string could be 
+of bytes.  A codec is able to determine if an encoded string could be decoded
+with it.
 */
 class StringCodec
 {
@@ -39,13 +40,13 @@ public:
                function to put the result into the internal buffer.
                */
                virtual void encode_char(wchar_t) =0;
-               
+
                /**
                Encodes a string.
                */
                virtual void encode(const std::wstring &s)
                { for(std::wstring::const_iterator i=s.begin(); i!=s.end(); ++i) encode_char(*i); }
-               
+
                /**
                Brings the encoder back to its initial state.  This allows the encoded
                sequence to be extracted or flushed without loss of integrity.
@@ -62,7 +63,7 @@ public:
                Returns the number of bytes in the output buffer.
                */
                unsigned size() const { return buffer_.size(); }
-               
+
                /**
                Clears the encoded sequence.  Encoder state is left intact.
                */
@@ -90,11 +91,17 @@ public:
                { for(std::string::const_iterator i=s.begin(); i!=s.end(); ) decode_char(s, i); }
 
                /**
-               Ensures that all input has been processed.  An exception is thrown if
-               this is not the case.
+               Ensures that all input has been processed.  If this is not the case any
+               buffers are cleared and an exception is thrown,
                */
                virtual void sync() { }
 
+               /**
+               Resets the decoder, clearing a possibly erroneus state.  Does not flush
+               the internal buffer.
+               */
+               virtual void reset() { }
+
                const std::wstring &get() const { return buffer_; }
                unsigned size() const { return buffer_.size(); }
                void flush() { buffer_.clear(); }
@@ -116,7 +123,7 @@ protected:
 };
 
 /**
-Convenience function that decodes a string using the given codec. 
+Convenience function that decodes a string using the given codec.
 */
 template<class C>
 std::wstring decode(const std::string &s)