🛠️ More aliases and some harder snippet support for intended behaviors

documentation/source/api/encodings/any_encoding.rst

@@ -40,6 +40,10 @@ Aliases
 
 .. doxygentypedef:: ztd::text::any_encoding
 
+.. doxygentypedef:: ztd::text::compat_any_encoding
+
+.. doxygentypedef:: ztd::text::ucompat_any_encoding
+
 
 
 Base Template

include/ztd/text/any_encoding.hpp

@@ -161,6 +161,24 @@ namespace ztd { namespace text {
 	/// ztd::text::encoding_scheme first.
 	using any_encoding = any_byte_encoding<::std::byte>;
 
+	//////
+	/// @brief The canonical erased encoding type which uses a `char` as its code unit type and an @c
+	/// unicode_code_point as its code point type, with spans for input and output operations.
+	///
+	/// @remarks If the input encoding does not match `char`, it will be first wrapped in a
+	/// ztd::text::encoding_scheme first. Use this type when dealing with what are effectively byte stream inputs but
+	/// oriented in a legacy manner, such as old `std::string` or `<iostream>`-based work.
+	using compat_any_encoding = any_byte_encoding<char>;
+
+	//////
+	/// @brief The canonical erased encoding type which uses a `unsigned char` as its code unit type and an @c
+	/// unicode_code_point as its code point type, with spans for input and output operations.
+	///
+	/// @remarks If the input encoding does not match `unsigned char`, it will be first wrapped in a
+	/// ztd::text::encoding_scheme first. Use this type when dealing with what are effectively byte stream inputs but
+	/// oriented around a slightly more modern approach to proper unsigned data handling with `unsigned char`.
+	using ucompat_any_encoding = any_byte_encoding<unsigned char>;
+
 
 	ZTD_TEXT_INLINE_ABI_NAMESPACE_CLOSE_I_
 }} // namespace ztd::text

tests/snippets/source/transcode_to.cpp

@@ -33,9 +33,31 @@
 #include <catch2/catch_all.hpp>
 
 TEST_CASE("snippets/transcode_to/basic",
-     "transcode_to with a pass handler doing UTF-8 text does not run afoul with pivot values") {
-	std::string as_str = "test";
-	auto result        = ztd::text::transcode_to<std::string>(
-          as_str, ztd::text::execution, ztd::text::utf8, ztd::text::pass_handler);
-	REQUIRE(as_str == result.output);
+     "transcode_to with a pass handler doing UTF-8 through an any_encoding does not run afoul with pivot values") {
+	SECTION("using span changes") {
+		std::string input = "test";
+		ztd::text::any_encoding input_encoding(ztd::text::utf8);
+		auto result = ztd::text::transcode_to<std::string>(
+		     std::as_bytes(std::span<char>(input)), input_encoding, ztd::text::utf8, ztd::text::pass_handler);
+		REQUIRE(result.output == input);
+		REQUIRE(result.error_code == ztd::text::encoding_error::ok);
+		REQUIRE(!result.errors_were_handled());
+		REQUIRE(result.error_count == 0);
+		REQUIRE(ztd::ranges::empty(result.input));
+		REQUIRE(ztd::text::is_state_complete(result.from_state.get()));
+		REQUIRE(ztd::text::is_state_complete(result.to_state.get()));
+	}
+	SECTION("using any_byte_encoding") {
+		std::string input = "test";
+		ztd::text::any_byte_encoding<char> input_encoding(ztd::text::compat_utf8);
+		auto result
+		     = ztd::text::transcode_to<std::string>(input, input_encoding, ztd::text::utf8, ztd::text::pass_handler);
+		REQUIRE(input == result.output);
+		REQUIRE(result.error_code == ztd::text::encoding_error::ok);
+		REQUIRE(!result.errors_were_handled());
+		REQUIRE(result.error_count == 0);
+		REQUIRE(ztd::ranges::empty(result.input));
+		REQUIRE(ztd::text::is_state_complete(result.from_state.get()));
+		REQUIRE(ztd::text::is_state_complete(result.to_state.get()));
+	}
 }