--- /dev/null
+/* $Id$
+
+This file is part of libmspstrings
+Copyright © 2006-2007 Mikko Rasa
+Distributed under the LGPL
+*/
+
+#ifndef MSP_STRINGS_CODEC_H_
+#define MSP_STRINGS_CODEC_H_
+
+#include <string>
+#include <msp/core/except.h>
+
+namespace Msp {
+namespace Codecs {
+
+typedef int UnicodeChar;
+
+typedef std::basic_string<UnicodeChar> ustring;
+
+enum ErrorMode
+{
+ THROW_ON_ERROR,
+ IGNORE_ERRORS,
+ TRANSLITERATE
+};
+
+/**
+An exception thrown for all kinds of problems encountered while encoding or
+decoding strings.
+*/
+class CodecError: public Exception
+{
+public:
+ CodecError(const std::string &w_): Exception(w_) { }
+};
+
+/**
+Base class for string codecs. Use one of the derived classes or the function
+create_codec to create a specific codec.
+
+Unicode strings are represented as ustrings. An std::string is considered to
+be an encoded sequence of bytes. A codec is able to determine if an encoded
+string could be decoded with it.
+*/
+class Codec
+{
+public:
+ /**
+ Base class for string encoder.
+
+ Each codec class should contain an Encoder class derived from this. The
+ encode_char and transliterate functions must be overloaded. Some encoders
+ may find it useful or necessary to implement some other functions too
+ (particularly sync and reset for stateful codecs).
+ */
+ class Encoder
+ {
+ protected:
+ ErrorMode err_mode;
+
+ Encoder(ErrorMode em): err_mode(em) { }
+ public:
+ virtual ~Encoder() { }
+
+ /** Encodes a single unicode character. If the character can't be
+ represented in this encoding, error() should be called. */
+ virtual void encode_char(UnicodeChar ch, std::string &buf) = 0;
+
+ /** Encodes a unicode string. This is equivalent to calling encode_char
+ for each character in the string with the same buffer. */
+ virtual void encode(const ustring &str, std::string &buf);
+
+ std::string encode(const ustring &);
+
+ /** Procuces a sequence of bytes that will bring the encoder back to the
+ initial state. */
+ virtual void sync(std::string &buf) { (void)buf; }
+
+ /** Resets the encoder to the initial state without producing output. */
+ virtual void reset() { }
+
+ protected:
+ /** Handles an error depending on the error mode.
+
+ THROW_ON_ERROR: throws CodecError(msg)
+ IGNORE_ERRORS: does nothing
+ TRANSLITERATE: calls transliterate(ch, buf) */
+ void error(UnicodeChar ch, std::string &buf, const std::string &msg);
+
+ /** Attempts to produce an alternative encoding for a unicode character.
+ Typically this includes dropping accent marks or romanizing letters. */
+ virtual void transliterate(UnicodeChar ch, std::string &buf) = 0;
+ };
+
+ /**
+ Base class for string decoder.
+
+ Each codec class should contain an Decoder class derived from this.
+ */
+ class Decoder
+ {
+ protected:
+ ErrorMode err_mode;
+
+ Decoder(ErrorMode em): err_mode(em) { }
+ public:
+ virtual ~Decoder() { }
+
+ /** Decodes a single character from a string. The iterator is advanced
+ to the next character. For stateful codecs, -1 may be returned if a
+ state change sequence was decoded but no character followed it. If
+ invalid input is encountered, the error() function should be called and
+ the iterator advanced only if it doesn't throw. */
+ virtual UnicodeChar decode_char(const std::string &str, std::string::const_iterator &i) = 0;
+
+ /** Decodes a string. */
+ virtual void decode(const std::string &str, ustring &buf);
+
+ ustring decode(const std::string &);
+
+ /** Resets the decoder to the initial state. */
+ virtual void reset() { }
+
+ protected:
+ /** Handles an error depending on the error mode. The return value is
+ suitable for returning from decode_char.
+
+ THROW_ON_ERROR: throws CodecError(msg)
+ IGNORE_ERRORS: returns -1
+ TRANSLITERATE: return 0xFFFE */
+ UnicodeChar error(const std::string &msg);
+ };
+
+protected:
+ Codec() { }
+public:
+ virtual ~Codec() { }
+
+ /** Returns the name of the encoding handled by this codec. */
+ virtual const char *get_name() const = 0;
+
+ /** Creates an encoder for this codec. */
+ virtual Encoder *create_encoder(ErrorMode err_mode = THROW_ON_ERROR) const = 0;
+
+ /** Creates a decoder for this codec. */
+ virtual Decoder *create_decoder(ErrorMode err_mode = THROW_ON_ERROR) const = 0;
+
+ /** Determines whether the given string can be successfully decoded with
+ this codec. Note that this function returning true does not guarantee that
+ the string was actually encoded with this codec. In particular, many 8-bit
+ encodings are indistinguishable. */
+ virtual bool detect(const std::string &) const;
+};
+
+typedef Codec::Encoder Encoder;
+typedef Codec::Decoder Decoder;
+
+/** Convenience function that decodes a string. */
+template<class C>
+ustring decode(const std::string &s)
+{
+ typename C::Decoder dec;
+ ustring result;
+ dec.decode(s, result);
+ return result;
+}
+
+/** Convenience function that encodes a string. */
+template<class C>
+std::string encode(const ustring &s)
+{
+ typename C::Encoder enc;
+ std::string result;
+ enc.encode(s, result);
+ enc.sync(result);
+ return result;
+}
+
+/** Convenience function that transcodes a string from one codec to another. */
+template<class F, class T>
+std::string transcode(const std::string &s)
+{
+ typename F::Decoder from;
+ typename T::Encoder to;
+ ustring temp;
+ from.decode(s, temp);
+ std::string result;
+ to.encode(temp, result);
+ to.sync(result);
+ return result;
+}
+
+/** Creates a codec for an encoding by name. The caller is responsible for
+deleting the codec when it's no longer needed. */
+Codec *create_codec(const std::string &);
+
+/** Automatically detects the encoding of a string and creates a codec for it.
+The codec must be deleted when it's no longer needed. */
+Codec *detect_codec(const std::string &);
+
+} // namespace Codecs
+} // namespace Msp
+
+#endif
projects / libs / core.git / blobdiff