yyc12345
e682a87d25
- rename LIBCMO_DISABLE_COPY_MOVE -> YYCC_DEL_CLS_COPY_MOVE and LIBCMO_DEFAULT_COPY_MOVE -> YYCC_DEF_CLS_COPY_MOVE. - fix Vector declaration generator. throw exception when operator[] face invalid index, instead of do fallback. - rename VTAll.hpp -> VTInternal.hpp and VYUserAll -> VTAll.hpp for easy to understand. - fix project name error in Doxygen template. - replace all LIBCMO_OS_WIN32 to YYCC_OS == YYCC_OS_WINDOWS. - fix some compile error (involving utf8 encoding) but not the final result. - use correct way to include std-image library (use <> instead of "") - finish documentation for VTUtils.hpp and VTEncoding.hpp.
158 lines
6.4 KiB
C++
158 lines
6.4 KiB
C++
#pragma once
|
|
#include "VTUtils.hpp"
|
|
#include <string>
|
|
#include <string_view>
|
|
|
|
/**
|
|
* @brief The namespace providing platform independent encoding convertion solution.
|
|
* @details
|
|
* LibCmo is a cross-platform library.
|
|
* In different platform, they have their own encoding solution.
|
|
* So we create a universal encoding solution in this namespace like Python does.
|
|
* User only need input our universal language name,
|
|
* then they can convert same strings in different platforms.
|
|
*/
|
|
namespace LibCmo::EncodingHelper {
|
|
|
|
/**
|
|
* @brief The token for encoding convertion.
|
|
* @details
|
|
* If you want to use any encoding function provided by this namespace,
|
|
* you should fetch a proper token for it.
|
|
* This token records the encoding which you want to convert from / to.
|
|
*
|
|
* In underlying implementation, this token type is a pointer
|
|
* pointing to an allocated memory space recording you specified encoding infomations.
|
|
* So this token should only be fetched from CreateEncodingToken()
|
|
* and must be freed by DestroyEncodingToken() if you don't need it.
|
|
* Otherwise it will cause memory leak.
|
|
*/
|
|
using EncodingToken = void*;
|
|
/**
|
|
* @brief The invalid value of #EncodingToken.
|
|
* @details
|
|
* It represents an invalid encoding token.
|
|
* Any encoding token which equals to this value should not be used.
|
|
* In underlying implementation, it actually is \c nullptr.
|
|
* Because EncodingToken is just a raw pointer.
|
|
*/
|
|
constexpr EncodingToken INVALID_ENCODING_TOKEN = nullptr;
|
|
|
|
/**
|
|
* @brief Create encoding token by given universal encoding name.
|
|
* @param[in] enc_name Universal encoding name.
|
|
* @return
|
|
* The generated encoding token.
|
|
* #INVALID_ENCODING_TOKEN if fail to generate encoding token.
|
|
* Usually it means that your given encoding name is invalid.
|
|
* Please note any successfully generated encoding token must be freed by DestroyEncodingToken().
|
|
*/
|
|
EncodingToken CreateEncodingToken(const std::u8string_view& enc_name);
|
|
/**
|
|
* @brief Destroy given encoding token and free its associated resources.
|
|
* @param[in] token
|
|
* The encoding token to be destroyed.
|
|
* If token is #INVALID_ENCODING_TOKEN, this function does nothing.
|
|
*/
|
|
void DestroyEncodingToken(EncodingToken token);
|
|
|
|
/**
|
|
* @brief Convert native string to UTF8 string by given encoding.
|
|
* @param[in] src The native string view to be converted.
|
|
* @param[out] dst The variable holding converted UTF8 string result.
|
|
* @param[in] token
|
|
* The encoding used when converting.
|
|
* #INVALID_ENCODING_TOKEN causes function returns false.
|
|
* @return True if success, otherwise false.
|
|
*/
|
|
bool ToOrdinary(const std::u8string_view& src, std::string& dst, EncodingToken token);
|
|
/**
|
|
* @brief Convert native string to UTF8 string by given encoding.
|
|
* @param[in] src
|
|
* The pointer to native string to be converted.
|
|
* nullptr is allowed but it will result in that function returns false.
|
|
* @param[out] dst The variable holding converted UTF8 string result.
|
|
* @param[in] token
|
|
* The encoding used when converting.
|
|
* #INVALID_ENCODING_TOKEN causes function returns false.
|
|
* @return True if success, otherwise false.
|
|
*/
|
|
bool ToOrdinary(const char8_t* src, std::string& dst, EncodingToken token);
|
|
/**
|
|
* @brief Convert native string to UTF8 string by given encoding.
|
|
* @param[in] src The native string view to be converted.
|
|
* @param[in] token
|
|
* The encoding used when converting.
|
|
* #INVALID_ENCODING_TOKEN causes function returns false.
|
|
* @return
|
|
* Converted UTF8 string result. Empty string if function failed.
|
|
* Please note empty input will also produce empty result.
|
|
* For preventing this ambiguity, please use other overloads.
|
|
*/
|
|
std::string ToOrdinary(const std::u8string_view& src, EncodingToken token);
|
|
/**
|
|
* @brief Convert native string to UTF8 string by given encoding.
|
|
* @param[in] src
|
|
* The pointer to native string to be converted.
|
|
* nullptr is allowed but it will result in that function returns false.
|
|
* @param[in] token
|
|
* The encoding used when converting.
|
|
* #INVALID_ENCODING_TOKEN causes function returns false.
|
|
* @return
|
|
* Converted UTF8 string result. Empty string if function failed.
|
|
* Please note empty input will also produce empty result.
|
|
* For preventing this ambiguity, please use other overloads.
|
|
*/
|
|
std::string ToOrdinary(const char8_t* src, EncodingToken token);
|
|
|
|
/**
|
|
* @brief Convert UTF8 string to native string by given encoding.
|
|
* @param[in] src The UTF8 string view to be converted.
|
|
* @param[out] dst The variable holding converted native string result.
|
|
* @param[in] token
|
|
* The encoding used when converting.
|
|
* #INVALID_ENCODING_TOKEN causes function returns false.
|
|
* @return True if success, otherwise false.
|
|
*/
|
|
bool ToUTF8(const std::string_view& src, std::u8string& dst, EncodingToken token);
|
|
/**
|
|
* @brief Convert UTF8 string to native string by given encoding.
|
|
* @param[in] src
|
|
* The pointer to UTF8 string to be converted.
|
|
* nullptr is allowed but it will result in that function returns false.
|
|
* @param[out] dst The variable holding converted native string result.
|
|
* @param[in] token
|
|
* The encoding used when converting.
|
|
* #INVALID_ENCODING_TOKEN causes function returns false.
|
|
* @return True if success, otherwise false.
|
|
*/
|
|
bool ToUTF8(const char* src, std::u8string& dst, EncodingToken token);
|
|
/**
|
|
* @brief Convert UTF8 string to native string by given encoding.
|
|
* @param[in] src The UTF8 string view to be converted.
|
|
* @param[in] token
|
|
* The encoding used when converting.
|
|
* #INVALID_ENCODING_TOKEN causes function returns false.
|
|
* @return
|
|
* Converted native string result. Empty string if function failed.
|
|
* Please note empty input will also produce empty result.
|
|
* For preventing this ambiguity, please use other overloads.
|
|
*/
|
|
std::u8string ToUTF8(const std::string_view& src, EncodingToken token);
|
|
/**
|
|
* @brief Convert UTF8 string to native string by given encoding.
|
|
* @param[in] src
|
|
* The pointer to UTF8 string to be converted.
|
|
* nullptr is allowed but it will result in that function returns false.
|
|
* @param[in] token
|
|
* The encoding used when converting.
|
|
* #INVALID_ENCODING_TOKEN causes function returns false.
|
|
* @return
|
|
* Converted native string result. Empty string if function failed.
|
|
* Please note empty input will also produce empty result.
|
|
* For preventing this ambiguity, please use other overloads.
|
|
*/
|
|
std::u8string ToUTF8(const char* src, EncodingToken token);
|
|
|
|
}
|