🔨 Better reconstructible! By a lot!

- 🛠 Fix up a lot of type deduction errors in the core of the API.
- ✨ Play nicer with non-views in transcode; these changes should be proagated everywhere else!
- 📝 Solidify the new names in the documentation and prepared to cut off an updated version

CMakeLists.txt

@@ -87,7 +87,6 @@ endif()
 
 # # Dependencies
 # ztd.version
-include(FetchContent)
 FetchContent_Declare(ztd.version
 	GIT_REPOSITORY https://github.com/soasis/version
 	GIT_TAG main)
@@ -111,8 +110,6 @@ target_include_directories(ztd.text
 	INTERFACE
 		$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
 		$<INSTALL_INTERFACE:include>)
-target_compile_features(ztd.text INTERFACE $<${ztd-text-is-top-level}:cxx_std_20>)
-target_compile_options(ztd.text INTERFACE ${--disable-permissive})
 target_sources(ztd.text INTERFACE ${ztd.text.includes})
 target_link_libraries(ztd.text
 	INTERFACE

cmake/ztd.text-config.cmake.in

@@ -2,7 +2,7 @@
 
 if (TARGET ztd::text)
 	get_target_property(ZTD_TEXT_INCLUDE_DIRS
-		ztd.text.single INTERFACE_INCLUDE_DIRECTORIES)
+		ztd.text INTERFACE_INCLUDE_DIRECTORIES)
 	set_and_check(ZTD_TEXT_INCLUDE_DIRS "${ZTD_TEXT_INCLUDE_DIRS}")
 	if (TARGET ztd::cuneicode)
 		set(ZTD_TEXT_LIBRARIES ztd::text ztd::cuneicode)

documentation/source/api.rst

@@ -147,3 +147,4 @@ Result Types, Status Codes and Quality Aides
 	api/stateless_validate_result
 	api/validate_result
 	api/validate_transcode_result
+	api/propagate_error

documentation/source/api/conversions/count_code_units.rst → documentation/source/api/conversions/count_decodable.rst

@@ -28,28 +28,28 @@
 ..
 .. =============================================================================>
 
-count_code_units
-================
+count_encodable
+=================
 
-``ztd::text::count_code_units`` is a function that takes an input sequence of ``code_unit``\ s and attempts to count them, according to the error handler that is given. Because the error handler is included as part of the function call (and is provided by default is one is not passed in), the count operation will also continue to count if the error handler sets the ``error_code`` member of the result to ``ztd::text::encoding_error::ok`` but still performs some action. This is, for example, the case with :doc:`ztd::text::replacement_handler </api/error handlers/replacement_handler>` - output replacement code units or code points will be counted as part of the final count and returned with ``result.error_code == ztd::text::encoding_error::ok``. You can differentiate error-less text from non-error text by checking ``result.errors_were_handled()``, which will be true if the error handler is called regardless of whether or not the error handler "smooths" the problem over by inserting replacement characters, doing nothing, or otherwise.
+``ztd::text::count_encodable`` is a function that takes an input sequence of ``code_point``\ s and attempts to count them, according to the error handler that is given. Because the error handler is included as part of the function call (and is provided by default is one is not passed in), the count operation will also continue to count if the error handler sets the ``error_code`` member of the result to ``ztd::text::encoding_error::ok`` but still performs some action. This is, for example, the case with :doc:`ztd::text::replacement_handler </api/error handlers/replacement_handler>` - output replacement code units or code points will be counted as part of the final count and returned with ``result.error_code == ztd::text::encoding_error::ok``. You can differentiate error-less text from non-error text by checking ``result.errors_were_handled()``, which will be true if the error handler is called regardless of whether or not the error handler "smooths" the problem over by inserting replacement characters, doing nothing, or otherwise.
 
 The overloads of this function increase the level of control you have with each passed argument. At the last overload with four arguments, the function attempts to work call some extension points or falls back to the base function call in this order:
 
-- The ``text_count_code_units(input, encoding, handler, state)`` extension point, if possible.
+- The ``text_count_encodable(input, encoding, handler, state)`` extension point, if possible.
 - An internal, implementation-defined customization point.
-- The ``basic_count_code_units`` base function.
+- The ``basic_count_encodable`` base function.
 
-The base function call, ``basic_count_code_units``, simply performs the :doc:`core counting loop </design/converting/count code units>` using the :doc:`Lucky 7 </design/lucky 7>` design.
+The base function call, ``basic_count_encodable``, simply performs the :doc:`core counting loop </design/converting/count encodable>` using the :doc:`Lucky 7 </design/lucky 7>` design.
 
-During the ``basic_count_code_units`` loop, if it detects that there is a preferable ``text_count_code_units_one``, it will call that method as ``text_count_code_units_one(input, encoding, handler, state)`` inside of the loop rather than doing the core design.
+During the ``basic_count_encodable`` loop, if it detects that there is a preferable ``text_count_encodable_one``, it will call that method as ``text_count_encodable_one(input, encoding, handler, state)`` inside of the loop rather than doing the core design.
 
 .. note::
 
-	👉 This means that if you implement none of the extension points whatsoever, implementing the basic ``decode_one`` function on your Encoding Object type will guarantee a proper, working implementation.
+	👉 This means that if you implement none of the extension points whatsoever, implementing the basic ``encode_one`` function on your Encoding Object type will guarantee a proper, working implementation.
 
 .. note::
 
-	👉 If you need to call the "basic" form of this function that takes no secret implementation shortcuts or user-defined extension points, then call ``basic_count_code_units`` directly. This can be useful to stop infinity loops when your extension points cannot handle certain inputs and thereby needs to "delegate" to the basic case.
+	👉 If you need to call the "basic" form of this function that takes no secret implementation shortcuts or user-defined extension points, then call ``basic_count_encodable`` directly. This can be useful to stop infinity loops when your extension points cannot handle certain inputs and thereby needs to "delegate" to the basic case.
 
 
 
@@ -60,5 +60,5 @@ During the ``basic_count_code_units`` loop, if it detects that there is a prefer
 Functions
 ---------
 
-.. doxygengroup:: ztd_text_count_code_units
+.. doxygengroup:: ztd_text_count_encodable
 	:content-only:

documentation/source/api/conversions/count_encodable.rst

@@ -0,0 +1,64 @@
+.. =============================================================================
+..
+.. ztd.text
+.. Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+.. Contact: opensource@soasis.org
+..
+.. Commercial License Usage
+.. Licensees holding valid commercial ztd.text licenses may use this file in
+.. accordance with the commercial license agreement provided with the
+.. Software or, alternatively, in accordance with the terms contained in
+.. a written agreement between you and Shepherd's Oasis, LLC.
+.. For licensing terms and conditions see your agreement. For
+.. further information contact opensource@soasis.org.
+..
+.. Apache License Version 2 Usage
+.. Alternatively, this file may be used under the terms of Apache License
+.. Version 2.0 (the "License") for non-commercial use; you may not use this
+.. file except in compliance with the License. You may obtain a copy of the
+.. License at
+..
+..		http:..www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+.. =============================================================================>
+
+count_decodable
+================
+
+``ztd::text::count_decodable`` is a function that takes an input sequence of ``code_unit``\ s and attempts to count them, according to the error handler that is given. Because the error handler is included as part of the function call (and is provided by default is one is not passed in), the count operation will also continue to count if the error handler sets the ``error_code`` member of the result to ``ztd::text::encoding_error::ok`` but still performs some action. This is, for example, the case with :doc:`ztd::text::replacement_handler </api/error handlers/replacement_handler>` - output replacement code units or code points will be counted as part of the final count and returned with ``result.error_code == ztd::text::encoding_error::ok``. You can differentiate error-less text from non-error text by checking ``result.errors_were_handled()``, which will be true if the error handler is called regardless of whether or not the error handler "smooths" the problem over by inserting replacement characters, doing nothing, or otherwise.
+
+The overloads of this function increase the level of control you have with each passed argument. At the last overload with four arguments, the function attempts to work call some extension points or falls back to the base function call in this order:
+
+- The ``text_count_decodable(input, encoding, handler, state)`` extension point, if possible.
+- An internal, implementation-defined customization point.
+- The ``basic_count_decodable`` base function.
+
+The base function call, ``basic_count_decodable``, simply performs the :doc:`core counting loop </design/converting/count encodable>` using the :doc:`Lucky 7 </design/lucky 7>` design.
+
+During the ``basic_count_decodable`` loop, if it detects that there is a preferable ``text_count_decodable_one``, it will call that method as ``text_count_decodable_one(input, encoding, handler, state)`` inside of the loop rather than doing the core design.
+
+.. note::
+
+	👉 This means that if you implement none of the extension points whatsoever, implementing the basic ``decode_one`` function on your Encoding Object type will guarantee a proper, working implementation.
+
+.. note::
+
+	👉 If you need to call the "basic" form of this function that takes no secret implementation shortcuts or user-defined extension points, then call ``basic_count_decodable`` directly. This can be useful to stop infinity loops when your extension points cannot handle certain inputs and thereby needs to "delegate" to the basic case.
+
+
+
+~~~~~~~~~~~~
+
+
+
+Functions
+---------
+
+.. doxygengroup:: ztd_text_count_decodable
+	:content-only:

documentation/source/api/conversions/count_code_points.rst → documentation/source/api/conversions/count_transcodable.rst

@@ -28,28 +28,28 @@
 ..
 .. =============================================================================>
 
-count_code_points
-=================
+count_transcodable
+==================
 
-``ztd::text::count_code_points`` is a function that takes an input sequence of ``code_point``\ s and attempts to count them, according to the error handler that is given. Because the error handler is included as part of the function call (and is provided by default is one is not passed in), the count operation will also continue to count if the error handler sets the ``error_code`` member of the result to ``ztd::text::encoding_error::ok`` but still performs some action. This is, for example, the case with :doc:`ztd::text::replacement_handler </api/error handlers/replacement_handler>` - output replacement code units or code points will be counted as part of the final count and returned with ``result.error_code == ztd::text::encoding_error::ok``. You can differentiate error-less text from non-error text by checking ``result.errors_were_handled()``, which will be true if the error handler is called regardless of whether or not the error handler "smooths" the problem over by inserting replacement characters, doing nothing, or otherwise.
+``ztd::text::count_transcodable`` is a function that takes an input sequence of ``code_unit``\ s and attempts to count them, according to the error handler that is given. Because the error handler is included as part of the function call (and is provided by default is one is not passed in), the count operation will also continue to count if the error handler sets the ``error_code`` member of the result to ``ztd::text::encoding_error::ok`` but still performs some action. This is, for example, the case with :doc:`ztd::text::replacement_handler </api/error handlers/replacement_handler>` - output replacement code units or code points will be counted as part of the final count and returned with ``result.error_code == ztd::text::encoding_error::ok``. You can differentiate error-less text from non-error text by checking ``result.errors_were_handled()``, which will be true if the error handler is called regardless of whether or not the error handler "smooths" the problem over by inserting replacement characters, doing nothing, or otherwise.
 
 The overloads of this function increase the level of control you have with each passed argument. At the last overload with four arguments, the function attempts to work call some extension points or falls back to the base function call in this order:
 
-- The ``text_count_code_points(input, encoding, handler, state)`` extension point, if possible.
+- The ``text_count_transcodable(input, from_encoding, to_encoding, from_handler, to_handler, from_state, to_state)`` extension point, if possible.
 - An internal, implementation-defined customization point.
-- The ``basic_count_code_points`` base function.
+- The ``basic_count_transcodable`` base function.
 
-The base function call, ``basic_count_code_points``, simply performs the :doc:`core counting loop </design/converting/count code points>` using the :doc:`Lucky 7 </design/lucky 7>` design.
+The base function call, ``basic_count_transcodable``, simply performs the :doc:`core counting loop </design/converting/count transcodable>` using the :doc:`Lucky 7 </design/lucky 7>` design.
 
-During the ``basic_count_code_points`` loop, if it detects that there is a preferable ``text_count_code_points_one``, it will call that method as ``text_count_code_points_one(input, encoding, handler, state)`` inside of the loop rather than doing the core design.
+During the ``basic_count_transcodable`` loop, if it detects that there is a preferable ``text_count_transcodable_one``, it will call that method as ``text_count_transcodable_one(input, encoding, handler, state)`` inside of the loop rather than doing the core design.
 
 .. note::
 
-	👉 This means that if you implement none of the extension points whatsoever, implementing the basic ``encode_one`` function on your Encoding Object type will guarantee a proper, working implementation.
+	👉 This means that if you implement none of the extension points whatsoever, implementing the basic ``decode_one`` and ``encode_one`` functions on your Encoding Object type will guarantee a proper, working implementation.
 
 .. note::
 
-	👉 If you need to call the "basic" form of this function that takes no secret implementation shortcuts or user-defined extension points, then call ``basic_count_code_points`` directly. This can be useful to stop infinity loops when your extension points cannot handle certain inputs and thereby needs to "delegate" to the basic case.
+	👉 If you need to call the "basic" form of this function that takes no secret implementation shortcuts or user-defined extension points, then call ``basic_count_transcodable`` directly. This can be useful to stop infinity loops when your extension points cannot handle certain inputs and thereby needs to "delegate" to the basic case.
 
 
 
@@ -60,5 +60,5 @@ During the ``basic_count_code_points`` loop, if it detects that there is a prefe
 Functions
 ---------
 
-.. doxygengroup:: ztd_text_count_code_points
+.. doxygengroup:: ztd_text_count_transcodable
 	:content-only:

documentation/source/api/conversions/validate_decodable_as.rst

@@ -31,7 +31,7 @@
 validate_decodable_as
 =====================
 
-``ztd::text::validate_decodable_as`` is a function that takes an input sequence of ``code_unit``\ s and attempts to validate that they can be turned into the ``code_point``\ s of the provided encoding. Unlike the :doc:`ztd::text::count_code_units </api/conversions/validate_decodable_as>` function, this does not take an error handler. **Any** error, even if it would be corrected over, produces a stop in the algorithm and a :doc:`validate_result </api/validate_result>`/:doc:`stateless_validate_result </api/stateless_validate_result>` object gets returned with the ``.valid`` member set to false.
+``ztd::text::validate_decodable_as`` is a function that takes an input sequence of ``code_unit``\ s and attempts to validate that they can be turned into the ``code_point``\ s of the provided encoding. Unlike the :doc:`ztd::text::count_decodable </api/conversions/validate_decodable_as>` function, this does not take an error handler. **Any** error, even if it would be corrected over, produces a stop in the algorithm and a :doc:`validate_result </api/validate_result>`/:doc:`stateless_validate_result </api/stateless_validate_result>` object gets returned with the ``.valid`` member set to false.
 
 The overloads of this function increase the level of control with each passed argument. At the last overload with four arguments, the function attempts to work call some extension points or falls back to the base function call in this order:
 

documentation/source/api/conversions/validate_encodable_as.rst

@@ -31,7 +31,7 @@
 validate_encodable_as
 =====================
 
-``ztd::text::validate_encodable_as`` is a function that takes an input sequence of ``code_point``\ s and attempts to validate that they can be turned into the ``code_unit``\ s of the provided encoding. Unlike the :doc:`ztd::text::count_code_points </api/conversions/validate_encodable_as>` function, this does not take an error handler. **Any** error, even if it would be corrected over, produces a stop in the algorithm and a :doc:`validate_result </api/validate_result>`/:doc:`stateless_validate_result </api/stateless_validate_result>` object gets returned with the ``.valid`` member set to false.
+``ztd::text::validate_encodable_as`` is a function that takes an input sequence of ``code_point``\ s and attempts to validate that they can be turned into the ``code_unit``\ s of the provided encoding. Unlike the :doc:`ztd::text::count_encodable </api/conversions/validate_encodable_as>` function, this does not take an error handler. **Any** error, even if it would be corrected over, produces a stop in the algorithm and a :doc:`validate_result </api/validate_result>`/:doc:`stateless_validate_result </api/stateless_validate_result>` object gets returned with the ``.valid`` member set to false.
 
 The overloads of this function increase the level of control with each passed argument. At the last overload with four arguments, the function attempts to work call some extension points or falls back to the base function call in this order:
 

documentation/source/api/conversions/validate_transcodable_as.rst

@@ -31,7 +31,7 @@
 validate_transcodable_as
 ========================
 
-``ztd::text::validate_transcodable_as`` is a function that takes an input sequence of ``code_unit``\ s and attempts to validate that they can be turned into the ``code_point``\ s of the provided encoding. Unlike the :doc:`ztd::text::count_code_units </api/conversions/validate_transcodable_as>` function, this does not take an error handler. **Any** error, even if it would be corrected over, produces a stop in the algorithm and a :doc:`validate_result </api/validate_result>`/:doc:`stateless_validate_result </api/stateless_validate_result>` object gets returned with the ``.valid`` member set to false.
+``ztd::text::validate_transcodable_as`` is a function that takes an input sequence of ``code_unit``\ s and attempts to validate that they can be turned into the ``code_point``\ s of the provided encoding. Unlike the :doc:`ztd::text::count_decodable </api/conversions/validate_transcodable_as>` function, this does not take an error handler. **Any** error, even if it would be corrected over, produces a stop in the algorithm and a :doc:`validate_result </api/validate_result>`/:doc:`stateless_validate_result </api/stateless_validate_result>` object gets returned with the ``.valid`` member set to false.
 
 The overloads of this function increase the level of control with each passed argument. At the last overload with four arguments, the function attempts to work call some extension points or falls back to the base function call in this order: