yyc12345/YYCCommonplace
1
0
Fork 0
Code Activity

doc: finish encoding doc

Browse Source
This commit is contained in:
yyc12345
2026-01-15 13:48:41 +08:00
parent 17053f4ebf
commit 7a34057836
7 changed files with 670 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
doc/src/encoding/iconv.dox Normal file
View File

@@ -0,0 +1,166 @@
namespace yycc::encoding::iconv {
/**
\page encoding__iconv Iconv-based Codec
\section encoding__iconv__overview Overview
The Iconv-based encoding conversion module provides encoding conversion functionality using the iconv library.
This module is available when you are in POSIX system, or enable iconv support manually when configuring the library.
\section encoding__iconv__classes Available Classes
\subsection encoding__iconv__classes__char Char to/from UTF-8 Conversion
Convert between character encodings and UTF-8:
\code
#include <yycc/encoding/iconv.hpp>
// Example: Creating a converter from Latin-1 to UTF-8
CharToUtf8 converter("ISO-8859-1");
std::string latin1_text = "Café résumé naïve";
auto result = converter.to_utf8(latin1_text);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Creating a converter from UTF-8 to Latin-1
Utf8ToChar converter("ISO-8859-1");
std::u8string utf8_text = u8"Café résumé naïve";
auto result = converter.to_char(utf8_text);
if (result.has_value()) {
std::string latin1_text = result.value();
// Use latin1_text...
} else {
// Handle conversion error
}
\endcode
\subsection encoding__iconv__classes__wchar WChar to/from UTF-8 Conversion
Convert between wide character and UTF-8:
\code
#include <yycc/encoding/iconv.hpp>
// Example: Converting wide character to UTF-8
WcharToUtf8 converter;
std::wstring wide_text = L"Hello, 世界!";
auto result = converter.to_utf8(wide_text);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-8 to wide character
Utf8ToWchar converter;
std::u8string utf8_text = u8"Hello, 世界!";
auto result = converter.to_wchar(utf8_text);
if (result.has_value()) {
std::wstring wide_text = result.value();
// Use wide_text...
} else {
// Handle conversion error
}
\endcode
\subsection encoding__iconv__classes__utf16_utf32 UTF-8 to/from UTF-16/UTF-32 Conversion
Convert between UTF encodings:
\code
#include <yycc/encoding/iconv.hpp>
// Example: Converting UTF-8 to UTF-16
Utf8ToUtf16 converter;
std::u8string utf8_text = u8"Hello, 世界!";
auto result = converter.to_utf16(utf8_text);
if (result.has_value()) {
std::u16string utf16_text = result.value();
// Use utf16_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-16 to UTF-8
Utf16ToUtf8 converter;
std::u16string utf16_text = u"Hello, 世界!";
auto result = converter.to_utf8(utf16_text);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-8 to UTF-32
Utf8ToUtf32 converter;
std::u8string utf8_text = u8"Hello, 世界! 🌍";
auto result = converter.to_utf32(utf8_text);
if (result.has_value()) {
std::u32string utf32_text = result.value();
// Use utf32_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-32 to UTF-8
Utf32ToUtf8 converter;
std::u32string utf32_text = U"Hello, 世界! 🌍";
auto result = converter.to_utf8(utf32_text);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\section encoding__iconv__error_handling Error Handling
All functions in this module return a result containing either
a ConvError struct represents conversion errors, or the final converted string.
\code
#include <yycc/encoding/iconv.hpp>
CharToUtf8 converter("INVALID_ENCODING");
// Note: Constructor errors might be detected during conversion
std::string text = "Hello";
auto result = converter.to_utf8(text);
if (result.has_value()) {
std::u8string converted = result.value();
// Process successfully converted string
} else {
// Handle conversion failure
std::cout << "Conversion failed\n";
}
\endcode
*/
}

98
doc/src/encoding/stl.dox Normal file
View File

@@ -0,0 +1,98 @@
namespace yycc::encoding::stl {
/**
\page encoding__stl STL-based Codec
\section encoding__stl__overview Overview
The STL-based encoding conversion module provides cross-platform encoding conversion functionality using the standard library's codecvt facets.
This module is designed to handle conversions between UTF-8, UTF-16, and UTF-32 encodings using the standard C++ locale facilities.
\section encoding__stl__attentions Attentions
The underlying implementation of this module is deprecated by C++ STL and may be removed in future versions of C++.
So please use this module carefully or considering use our \ref pycodec module instead.
\section encoding__stl__functions Available Functions
\subsection encoding__stl__functions__utf16 UTF-8 to/from UTF-16 Conversion
Convert between UTF-8 and UTF-16 encodings using standard library facilities:
\code
#include <yycc/encoding/stl.hpp>
// Example: Converting UTF-8 to UTF-16
std::u8string utf8_text = u8"Hello, 世界!";
auto result = to_utf16(utf8_text);
if (result.has_value()) {
std::u16string utf16_text = result.value();
// Use utf16_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-16 to UTF-8
std::u16string utf16_text = u"Hello, 世界!";
auto result = to_utf8(utf16_text);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\subsection encoding__stl__functions__utf32 UTF-8 to/from UTF-32 Conversion
Convert between UTF-8 and UTF-32 encodings:
\code
#include <yycc/encoding/stl.hpp>
// Example: Converting UTF-8 to UTF-32
std::u8string utf8_text = u8"Hello, 世界! 🌍";
auto result = to_utf32(utf8_text);
if (result.has_value()) {
std::u32string utf32_text = result.value();
// Use utf32_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-32 to UTF-8
std::u32string utf32_text = U"Hello, 世界! 🌍";
auto result = to_utf8(utf32_text);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\section encoding__stl__error_handling Error Handling
All functions in this module return a result containing either
a ConvError struct represents conversion errors, or the final converted string.
\code
#include <yycc/encoding/stl.hpp>
std::u8string invalid_utf8 = "\xFF\xFE"; // Invalid UTF-8 sequence
auto result = to_utf16(invalid_utf8);
if (result.has_value()) {
std::u16string converted = result.value();
// Process successfully converted string
} else {
// Handle conversion failure
std::cout << "Conversion failed\n";
}
\endcode
*/
}

191
doc/src/encoding/windows.dox Normal file
View File

@@ -0,0 +1,191 @@
namespace yycc::encoding::windows {
/**
\page encoding__windows Win32-based Codec
\section encoding__windows__overview Overview
The Windows-specific encoding conversion module provides encoding conversion functionality
using Windows API functions such as `WideCharToMultiByte` and `MultiByteToWideChar`.
This module is available only on Windows platforms and offers efficient conversion
between various character encodings including wide character, multi-byte, and UTF-8.
\section encoding__windows__functions Available Functions
\subsection encoding__windows__functions__wchar Wide Character to/from Multi-byte Conversion
Convert between wide character strings and multi-byte strings using Windows code pages:
\code
#include <yycc/encoding/windows.hpp>
// Example: Converting wide character string to multi-byte with specific code page
std::wstring wide_text = L"Hello, 世界!";
auto result = to_char(wide_text, CP_UTF8); // Using UTF-8 code page
if (result.has_value()) {
std::string multi_byte_text = result.value();
// Use multi_byte_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting multi-byte string to wide character with specific code page
std::string multi_byte_text = "Hello, 世界!";
auto result = to_wchar(multi_byte_text, CP_UTF8);
if (result.has_value()) {
std::wstring wide_text = result.value();
// Use wide_text...
} else {
// Handle conversion error
}
\endcode
\subsection encoding__windows__functions__mbcs Multi-byte to/from Multi-byte Conversion
Convert between different multi-byte encodings by using wide character as an intermediate:
\code
#include <yycc/encoding/windows.hpp>
// Example: Converting between two different code pages
std::string source_text = "Hello, world!";
auto result = to_char(source_text, CP_ACP, CP_UTF8); // ANSI to UTF-8
if (result.has_value()) {
std::string utf8_text = result.value();
// Use converted UTF-8 text...
} else {
// Handle conversion error
}
\endcode
\subsection encoding__windows__functions__utf8 UTF-8 Specific Conversions
Specialized functions for UTF-8 conversion without requiring explicit code page specification:
\code
#include <yycc/encoding/windows.hpp>
// Example: Converting wide character to UTF-8
std::wstring wide_text = L"Hello, 世界!";
auto result = to_utf8(wide_text);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-8 to wide character
std::u8string utf8_text = u8"Hello, 世界!";
auto result = to_wchar(utf8_text);
if (result.has_value()) {
std::wstring wide_text = result.value();
// Use wide_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting multi-byte to UTF-8
std::string multi_byte_text = "Hello, world!";
auto result = to_utf8(multi_byte_text, CP_ACP);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-8 to multi-byte
std::u8string utf8_text = u8"Hello, world!";
auto result = to_char(utf8_text, CP_ACP);
if (result.has_value()) {
std::string multi_byte_text = result.value();
// Use multi_byte_text...
} else {
// Handle conversion error
}
\endcode
\subsection encoding__windows__functions__utf16_utf32 UTF-8 to/from UTF-16/UTF-32 Conversion
Available on Windows with Microsoft STL for conversion between UTF encodings:
\code
#include <yycc/encoding/windows.hpp>
// Example: Converting UTF-8 to UTF-16
std::u8string utf8_text = u8"Hello, 世界!";
auto result = to_utf16(utf8_text);
if (result.has_value()) {
std::u16string utf16_text = result.value();
// Use utf16_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-16 to UTF-8
std::u16string utf16_text = u"Hello, 世界!";
auto result = to_utf8(utf16_text);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-8 to UTF-32
std::u8string utf8_text = u8"Hello, 世界! 🌍";
auto result = to_utf32(utf8_text);
if (result.has_value()) {
std::u32string utf32_text = result.value();
// Use utf32_text...
} else {
// Handle conversion error
}
\endcode
\code
// Example: Converting UTF-32 to UTF-8
std::u32string utf32_text = U"Hello, 世界! 🌍";
auto result = to_utf8(utf32_text);
if (result.has_value()) {
std::u8string utf8_text = result.value();
// Use utf8_text...
} else {
// Handle conversion error
}
\endcode
\section encoding__windows__error_handling Error Handling
All functions in this module return a result containing either
a ConvError struct represents conversion errors, or the final converted string.
\code
#include <yycc/encoding/windows.hpp>
std::wstring invalid_text = /* some problematic string */;
auto result = to_char(invalid_text, CP_UTF8);
if (result.has_value()) {
std::string converted = result.value();
// Process successfully converted string
} else {
// Handle conversion failure
std::cout << "Conversion failed\n";
}
\endcode
*/
}