diff options
| -rw-r--r-- | common/encoding.h | 155 |
1 files changed, 154 insertions, 1 deletions
diff --git a/common/encoding.h b/common/encoding.h index bccfb36b0a..b55c485efd 100644 --- a/common/encoding.h +++ b/common/encoding.h @@ -37,37 +37,190 @@ typedef void* iconv_t; namespace Common { +/** + * A class, that allows conversion between different text encoding, + * the encodings available depend on the current backend and if the + * ScummVM is compiled with or without iconv. + */ class Encoding { public: + /** + * Constructs everything needed for the conversion between 2 encodings + * and saves the values for future use. + * + * @param to Name of the encoding the strings will be converted to + * @param from Name of the encoding the strings will be converted from + */ Encoding(const String &to, const String &from); ~Encoding(); + /** + * Converts string between encodings. The resulting string is ended by + * a character with value 0 (C-like ending for 1 byte per character + * encodings, 2 zero bytes for UTF-16, 4 zero bytes for UTF-32) + * + * The result has to be freed after use. + * + * @param string String that should be converted. + * @param length Length of the string to convert in bytes. + * + * @return Converted string (must be freed) or nullptr if the conversion failed + */ char *convert(const char *string, size_t length); + + /** + * Static version of the method above. + * Converts string between encodings. The resulting string is ended by + * a character with value 0 (C-like ending for 1 byte per character + * encodings, 2 zero bytes for UTF-16, 4 zero bytes for UTF-32) + * + * The result has to be freed after use. + * + * @param to Name of the encoding the strings will be converted to + * @param from Name of the encoding the strings will be converted from + * @param string String that should be converted. + * @param length Length of the string to convert in bytes. + * + * @return Converted string (must be freed) or nullptr if the conversion failed + */ static char *convert(const String &to, const String &from, const char *string, size_t length); + /** + * @return The encoding, which is currently being converted from + */ String getFrom() {return _from;}; + + /** + * @param from The encoding, to convert from + */ void setFrom(const String &from) {_from = from;}; + /** + * @return The encoding, which is currently being converted to + */ String getTo() {return _to;}; + + /** + * @param to The encoding, to convert to + */ void setTo(const String &to) {_to = to;}; private: + /** The encoding, which is currently being converted to */ String _to; + + /** The encoding, which is currently being converted from */ String _from; + /** + * iconvHandle currently used for conversions (is void pointer to 0 + * if the ScummVM isn't compiled with iconv) + */ + iconv_t _iconvHandle; + + /** + * Takes care of transliteration and calls conversion2 for the encoding + * conversion + * + * The result has to be freed after use. + * + * @param iconvHandle Handle to use for the conversion + * @param to Name of the encoding the strings will be converted to + * @param from Name of the encoding the strings will be converted from + * @param string String that should be converted. + * @param length Length of the string to convert in bytes. + * + * @return Converted string (must be freed) or nullptr if the conversion failed + */ static char *conversion(iconv_t iconvHandle, const String &to, const String &from, const char *string, size_t length); + /** + * Calls as many conversion functions as possible or until the conversion + * succeeds. It first tries to use iconv, then it tries to use platform + * specific functions and after that it tries to use TransMan mapping. + * + * The result has to be freed after use. + * + * @param iconvHandle Handle to use for the conversion + * @param to Name of the encoding the strings will be converted to + * @param from Name of the encoding the strings will be converted from + * @param string String that should be converted. + * @param length Length of the string to convert in bytes. + * + * @return Converted string (must be freed) or nullptr if the conversion failed + */ static char *conversion2(iconv_t iconvHandle, const String &to, const String &from, const char *string, size_t length); - iconv_t _iconvHandle; + /** + * Tries to convert the string using iconv. + * + * The result has to be freed after use. + * + * @param iconvHandle Handle to use for the conversion + * @param string String that should be converted. + * @param length Length of the string to convert in bytes. + * + * @return Converted string (must be freed) or nullptr if the conversion failed + */ static char *convertIconv(iconv_t iconvHandle, const char *string, size_t length); + /** + * Tries to use the TransMan to convert the string. It can convert only + * between UTF-32 and the current GUI charset. It also tries to convert + * from the current GUI charset to UTF-32 and then it calls convert() again. + * + * The result has to be freed after use. + * + * @param to Name of the encoding the strings will be converted to + * @param from Name of the encoding the strings will be converted from + * @param string String that should be converted. + * @param length Length of the string to convert in bytes. + * + * @return Converted string (must be freed) or nullptr if the conversion failed + */ static char *convertTransManMapping(const char *to, const char *from, const char *string, size_t length); + /** + * Transliterates cyrilic string in iso-8859-5 encoding and returns + * it's ASCII (latin) form. + * + * The result has to be freed after use. + * + * @param string String that should be converted + * + * @return Transliterated string in ASCII (must be freed) or nullptr on fail. + */ static char *transliterateCyrilic(const char *string); + + /** + * Transliterates cyrilic in UTF-32 string. + * + * The result has to be freed after use. + * + * @param string String that should be converted + * @param length Length of the string in bytes + * + * @return Transliterated string in UTF-32 (must be freed) or nullptr on fail. + */ static uint32 *transliterateUTF32(const uint32 *string, size_t length); + /** + * Inits the iconv handle + * + * The result has to be freed after use. + * + * @param to Name of the encoding the strings will be converted to + * @param from Name of the encoding the strings will be converted from + * + * @return Opened iconv handle or 0 if ScummVM is compiled without iconv + */ static iconv_t initIconv(const String &to, const String &from); + + /** + * Deinits the iconv handle + * + * @param iconvHandle Handle that should be deinited + */ static void deinitIconv(iconv_t iconvHandle); }; |