✨validate_transcodable_as

- 🎨 Improvements to the constexpr processing
- ✨ Added __clang_literal_encoding__ and __clang_wide_literal_encoding__ understanding
- ✔ Vastly improved endianess tests
- 🔨 Fixed up tests for different platforms and for certain compiler errors
- 📝Write up a bit better documentations for some portions, fix inline shenanigans (Closes #9)
- ✨ Add a CONTRIBUTING file
- 🔨 Fix reconstructibility and noexceptness related to certain kinds of iterators (Closes and Fixes #11 and #12)
- 📝 Make sure commercial vs. non-commercial is specified more clearly in the LICENSE file

CMakeLists.txt

@@ -135,6 +135,15 @@ string(CONCAT --extra-constexpr-power
 		>
 	>
 )
+string(CONCAT --template-debugging-mode
+	$<IF:$<BOOL:${MSVC}>,
+		,
+		$<IF:$<BOOL:${CLANG}>,
+			-ftemplate-backtrack-limit=0,
+			-ftemplate-backtrace-limit=0
+		>
+	>
+)
 string(CONCAT ztd-use-cuneicode $<
 	$<AND:
 		$<BOOL:${ZTD_TEXT_USE_CUNEICODE}>,

CONTRIBUTING

@@ -0,0 +1,11 @@
+Thank you for considering a contribution to this library!
+
+By contributing to this library, you agree that your contributions will be released to the copyright of JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.
+
+If you're okay with the License and such, you will be asked to sign a Contributor License Agreement to contribute to the core library if need be!
+
+Code should be formatted using the provide [`.clang-format`](.clang-format). If it does a terrible job, then hand-format it with the proper indentation (using tabs) and alignment (using spaces) in-between `// clang-format off` and `// clang-format on` comment lines.
+
+If you are contributing new code, it is a good idea to include a test case or two in the relevant test area for run-time, compile-time, or more. If those tests need data files, they can be generated through CMake when necessary or, if small enough, stored in the repository itself to be used and then copied to a proper directory for the test or example code. See the [example CMakeLists.txt for the "basic" examples](examples/basic/CMakeLists.txt) for a minor demonstration for built-in data and source and how to organize and copy it.
+
+If you are contributing fixes, make sure to test those fixes as best as you can by adding test cases or example code that exercises those fixes! If it is performance related, write a benchmark for it so it can become part of the data we track for this.

LICENSE

@@ -59,4 +59,24 @@ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
 
+END OF TERMS AND CONDITIONS
+
+
+
+
+            COMMERCIAL LICENSE PROVISIONS
+
+ztd.text
+Commerical License Usage
+Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+Contact: opensource@soasis.org
+
+
+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.
+
 END OF TERMS AND CONDITIONS

README.md

@@ -18,3 +18,10 @@ Please considering sponsoring the work via [any of the available means listed ne
 # Documentation
 
 The documentation can be found in full on [https://ztdtext.rtfd.io/](https://ztdtext.rtfd.io/)!
+
+
+
+
+# License & Contributions
+
+By contributing to this repository, you agree that your contributions will be released to the copyright of JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC under the Apache 2.0 License or the relevant Commercial License. See the [LICENSE](LICENSE) file and the [CONTRIBUTING](CONTRIBUTING) file for details.

documentation/source/_static/inline_removal.js

@@ -0,0 +1,33 @@
+// =============================================================================
+//
+// 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.
+//
+// ============================================================================>
+
+$(document).ready(function () {
+	$("em.property > span.pre:contains('inline')").hide();
+});

documentation/source/api.rst

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

documentation/source/api/conversions/validate_decodable_as.rst

@@ -0,0 +1,67 @@
+.. =============================================================================
+..
+.. 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.
+..
+.. =============================================================================>
+
+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.
+
+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:
+
+- The ``text_validate_decodable_as(input, encoding, decode_state)`` extension point, if possible.
+- The ``text_validate_decodable_as(input, encoding, decode_state, encode_state)`` extension point, if possible.
+- An internal, implementation-defined customization point.
+- The ``basic_validate_decodable_as`` base function.
+
+The base function call, ``basic_validate_decodable_as``, simply performs the :doc:`core validating loop </design/converting/validate decodable>` using the :doc:`Lucky 7 </design/lucky 7>` design. The reason the last overload takes 2 state arguments is due to how the base implementation works from the core validating loop. If during the 3-argument overload it is detected that ``text_validate_decodable_as(input, encoding, decode_state)`` can be called, it will be called without attempt to create an ``encode_state`` value with :doc:`ztd::text::make_encode_state(...) </api/make_encode_state>`.
+
+During the ``basic_validate_decodable_as`` loop, if it detects that there is a preferable ``text_validate_decodable_as_one``, it will call that method as ``text_validate_decodable_as_one(input, encoding, decode_state)`` inside of the loop rather than doing the core design.
+
+The :doc:`ztd::text::validate_result </api/validate_result>` type only includes the ``decode_state`` in all cases.
+
+.. note::
+
+	👉 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_validate_decodable_as`` 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_validate_decodable_as
+	:content-only:

documentation/source/api/conversions/validate_code_points.rst → documentation/source/api/conversions/validate_encodable_as.rst

@@ -28,21 +28,21 @@
 ..
 .. =============================================================================>
 
-validate_code_points
-====================
+validate_encodable_as
+=====================
 
-``ztd::text::validate_code_points`` 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_code_points>` 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_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.
 
 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:
 
-- The ``text_validate_code_points(input, encoding, encode_state)`` extension point, if possible.
-- The ``text_validate_code_points(input, encoding, encode_state, decode_state)`` extension point, if possible.
+- The ``text_validate_encodable_as(input, encoding, encode_state)`` extension point, if possible.
+- The ``text_validate_encodable_as(input, encoding, encode_state, decode_state)`` extension point, if possible.
 - An internal, implementation-defined customization point.
-- The ``basic_validate_code_points`` base function.
+- The ``basic_validate_encodable_as`` base function.
 
-The base function call, ``basic_validate_code_points``, simply performs the :doc:`core validating loop </design/converting/validate code units>` using the :doc:`Lucky 7 </design/lucky 7>` design. The reason the last overload takes 2 state arguments is due to how the base implementation works from the core validating loop. If during the 3-argument overload it is detected that ``text_validate_code_points(input, encoding, encode_state)`` can be called, it will be called without attempt to create an ``decode_state`` value with :doc:`ztd::text::make_decode_state(...) </api/make_decode_state>`.
+The base function call, ``basic_validate_encodable_as``, simply performs the :doc:`core validating loop </design/converting/validate decodable>` using the :doc:`Lucky 7 </design/lucky 7>` design. The reason the last overload takes 2 state arguments is due to how the base implementation works from the core validating loop. If during the 3-argument overload it is detected that ``text_validate_encodable_as(input, encoding, encode_state)`` can be called, it will be called without attempt to create an ``decode_state`` value with :doc:`ztd::text::make_decode_state(...) </api/make_decode_state>`.
 
-During the ``basic_validate_code_points`` loop, if it detects that there is a preferable ``text_validate_code_units_one``, it will call that method as ``text_validate_code_points_one(input, encoding, encode_state)`` inside of the loop rather than doing the core design.
+During the ``basic_validate_encodable_as`` loop, if it detects that there is a preferable ``text_validate_decodable_as_one``, it will call that method as ``text_validate_encodable_as_one(input, encoding, encode_state)`` inside of the loop rather than doing the core design.
 
 The :doc:`ztd::text::validate_result </api/validate_result>` type only includes the ``encode_state`` in all cases.
 
@@ -52,7 +52,7 @@ The :doc:`ztd::text::validate_result </api/validate_result>` type only includes
 
 .. 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_validate_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_validate_encodable_as`` 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.
 
 
 
@@ -63,5 +63,5 @@ The :doc:`ztd::text::validate_result </api/validate_result>` type only includes
 Functions
 ---------
 
-.. doxygengroup:: ztd_text_validate_code_points
+.. doxygengroup:: ztd_text_validate_encodable_as
 	:content-only:

documentation/source/api/conversions/validate_code_units.rst → documentation/source/api/conversions/validate_transcodable_as.rst

@@ -28,21 +28,20 @@
 ..
 .. =============================================================================>
 
-validate_code_units
-===================
+validate_transcodable_as
+========================
 
-``ztd::text::validate_code_units`` 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_code_units>` 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_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.
 
 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:
 
-- The ``text_validate_code_units(input, encoding, decode_state)`` extension point, if possible.
-- The ``text_validate_code_units(input, encoding, decode_state, encode_state)`` extension point, if possible.
+- The ``text_validate_transcodable_as(input, from_encoding, to_encoding, decode_state, encode_state)`` extension point, if possible.
 - An internal, implementation-defined customization point.
-- The ``basic_validate_code_units`` base function.
+- The ``basic_validate_transcodable_as`` base function.
 
-The base function call, ``basic_validate_code_units``, simply performs the :doc:`core validating loop </design/converting/validate code units>` using the :doc:`Lucky 7 </design/lucky 7>` design. The reason the last overload takes 2 state arguments is due to how the base implementation works from the core validating loop. If during the 3-argument overload it is detected that ``text_validate_code_units(input, encoding, decode_state)`` can be called, it will be called without attempt to create an ``encode_state`` value with :doc:`ztd::text::make_encode_state(...) </api/make_encode_state>`.
+The base function call, ``basic_validate_transcodable_as``, simply performs the :doc:`core validating loop </design/converting/validate decodable>` using the :doc:`Lucky 7 </design/lucky 7>` design. The reason the last overload takes 2 state arguments is due to how the base implementation works from the core validating loop. If during the 3-argument overload it is detected that ``text_validate_transcodable_as(input, encoding, decode_state)`` can be called, it will be called without attempt to create an ``encode_state`` value with :doc:`ztd::text::make_encode_state(...) </api/make_encode_state>`.
 
-During the ``basic_validate_code_units`` loop, if it detects that there is a preferable ``text_validate_code_units_one``, it will call that method as ``text_validate_code_units_one(input, encoding, decode_state)`` inside of the loop rather than doing the core design.
+During the ``basic_validate_transcodable_as`` loop, if it detects that there is a preferable ``text_validate_transcodable_as_one``, it will call that method as ``text_validate_transcodable_as_one(input, encoding, decode_state)`` inside of the loop rather than doing the core design.
 
 The :doc:`ztd::text::validate_result </api/validate_result>` type only includes the ``decode_state`` in all cases.
 
@@ -52,7 +51,7 @@ The :doc:`ztd::text::validate_result </api/validate_result>` type only includes
 
 .. 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_validate_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_validate_transcodable_as`` 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.
 
 
 
@@ -63,5 +62,5 @@ The :doc:`ztd::text::validate_result </api/validate_result>` type only includes
 Functions
 ---------
 
-.. doxygengroup:: ztd_text_validate_code_units
+.. doxygengroup:: ztd_text_validate_transcodable_as
 	:content-only: