Complete tests and finish v0 of the documentation!

- It's RELEASE TIME! 🎉
soasis · Feb 21, 2021 · 1fb3b44 · 1fb3b44
1 parent ad00abe
commit 1fb3b44
Show file tree

Hide file tree

Showing 135 changed files with 3,856 additions and 1,595 deletions.
diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt
@@ -64,10 +64,15 @@ file(GLOB_RECURSE ztd_text_sphinx_sources LIST_DIRECTORIES false CONFIGURE_DEPEN
 #Replace variables inside @@ with the current values
 configure_file(${ZTD_TEXT_DOXYFILE_IN} ${ZTD_TEXT_DOXYFILE_OUT} @ONLY)
 
-# Ensure Doxygen won't crash because it doesn't create directories for us
+# Ensure Doxygen/Sphinx won't crash because it doesn't create directories for us
 file(MAKE_DIRECTORY ${ZTD_TEXT_DOXYGEN_OUTPUT_DIR})
 file(MAKE_DIRECTORY ${ZTD_TEXT_DOXYGEN_XML_OUTPUT_DIR})
 file(MAKE_DIRECTORY ${ZTD_TEXT_DOXYGEN_HTML_OUTPUT_DIR})
+file(MAKE_DIRECTORY ${ZTD_TEXT_SPHINX_BUILD_DIR})
+
+set_directory_properties(PROPERTIES ADDITIONAL_CLEAN_FILES
+	"${ZTD_TEXT_DOXYGEN_OUTPUT_DIR};${ZTD_TEXT_DOXYGEN_XML_OUTPUT_DIR};${ZTD_TEXT_DOXYGEN_HTML_OUTPUT_DIR};${ZTD_TEXT_SPHINX_BUILD_DIR}"
+)
 
 add_custom_command(OUTPUT ${ZTD_TEXT_DOXYGEN_INDEX_FILE}
 	COMMAND ${DOXYGEN_EXECUTABLE} ${ZTD_TEXT_DOXYFILE_OUT}

diff --git a/documentation/source/api.rst b/documentation/source/api.rst
@@ -35,6 +35,17 @@ This is simply a listing of all the available pages containing various APIs, or
 
 
 
+Containers
+----------
+
+.. toctree::
+	:maxdepth: 1
+	:glob:
+
+	api/containers/*
+
+
+
 Views
 -----
 
@@ -46,7 +57,6 @@ Views
 
 
 
-
 Encodings
 ---------
 
@@ -88,10 +98,10 @@ Properties and Classifications
 .. toctree::
 	:maxdepth: 1
 
-	api/code_point_of
-	api/code_unit_of
-	api/decode_state_of
-	api/encode_state_of
+	api/code_point
+	api/code_unit
+	api/decode_state
+	api/encode_state
 	api/max_code_points
 	api/max_code_units
 	api/is_state_independent
@@ -103,9 +113,10 @@ Properties and Classifications
 	api/is_code_points_replaceable
 	api/is_ignorable_error_handler
 	api/is_unicode_encoding
-	api/maybe_is_unicode_encoding
+	api/contains_unicode_encoding
 	api/is_unicode_code_point
 	api/is_unicode_scalar_value
+	api/is_transcoding_compatible
 	api/default_code_point_encoding
 	api/default_code_unit_encoding
 

diff --git a/documentation/source/api/code_point_of.rst → documentation/source/api/code_point.rst b/documentation/source/api/code_point_of.rst → documentation/source/api/code_point.rst
@@ -28,10 +28,10 @@
 ..
 .. =============================================================================>
 
-code_point_of
+code_point
 ===================
 
-.. doxygenclass:: ztd::text::code_point_of
+.. doxygenclass:: ztd::text::code_point
 	:members:
 
-.. doxygentypedef:: ztd::text::code_point_of_t
+.. doxygentypedef:: ztd::text::code_point_t
diff --git a/documentation/source/api/code_unit_of.rst → documentation/source/api/code_unit.rst b/documentation/source/api/code_unit_of.rst → documentation/source/api/code_unit.rst
@@ -28,10 +28,10 @@
 ..
 .. =============================================================================>
 
-code_unit_of
+code_unit
 ==================
 
-.. doxygenclass:: ztd::text::code_unit_of
+.. doxygenclass:: ztd::text::code_unit
 	:members:
 
-.. doxygentypedef:: ztd::text::code_unit_of_t
+.. doxygentypedef:: ztd::text::code_unit_t
diff --git a/documentation/source/api/containers/basic_text.rst b/documentation/source/api/containers/basic_text.rst
@@ -0,0 +1,55 @@
+.. =============================================================================
+..
+.. 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.
+..
+.. =============================================================================>
+
+🔨 basic_text (In Progress)
+===========================
+
+.. warning::
+
+	|unfinished_warning|
+
+The ``basic_text`` class provides functionality similar to ``std::string`` but for performing it on encoded, normalized text.
+
+.. doxygenclass:: ztd::text::basic_text
+	:members:
+
+.. doxygentypedef:: ztd::text::text
+
+.. doxygentypedef:: ztd::text::wtext
+
+.. doxygentypedef:: ztd::text::ltext
+
+.. doxygentypedef:: ztd::text::wltext
+
+.. doxygentypedef:: ztd::text::u8text
+
+.. doxygentypedef:: ztd::text::u16text
+
+.. doxygentypedef:: ztd::text::u32text
diff --git a/documentation/source/api/contains_unicode_encoding.rst b/documentation/source/api/contains_unicode_encoding.rst
@@ -0,0 +1,43 @@
+.. =============================================================================
+..
+.. 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.
+..
+.. =============================================================================>
+
+contains_unicode_encoding
+=========================
+
+This function determines whether or not the type is or contains a unicode encoding. This means any encoding wherein the entirety of Unicode, all 21 bits, can be represented without loss of information. For a full list of encodings which are considered Unicode Encodings by this library, see :doc:`the Known Unicode Encodings list</known unicode encodings>`.
+
+This function checks for 2 things.
+
+- It checks to see if the call ``encoding.contains_unicode_encoding()`` is well-formed and returns a boolean value. If this is the case, it calls ``encoding.contains_unicode_encoding()`` and returns that value.
+- It looks to see if the provided ``encoding`` has a member type called ``::is_unicode_encoding``. If this is the case, then it returns ``is_unicode_encoding_v<Type>``.
+
+If none of these work, then it returns ``false``.
+
+.. doxygenfunction:: ztd::text::contains_unicode_encoding
diff --git a/documentation/source/api/decode_state_of.rst → documentation/source/api/decode_state.rst b/documentation/source/api/decode_state_of.rst → documentation/source/api/decode_state.rst
@@ -28,10 +28,10 @@
 ..
 .. =============================================================================>
 
-decode_state_of
+decode_state
 ===============
 
-.. doxygenclass:: ztd::text::decode_state_of
+.. doxygenclass:: ztd::text::decode_state
 	:members:
 
-.. doxygentypedef:: ztd::text::decode_state_of_t
+.. doxygentypedef:: ztd::text::decode_state_t
diff --git a/documentation/source/api/encode_state_of.rst → documentation/source/api/encode_state.rst b/documentation/source/api/encode_state_of.rst → documentation/source/api/encode_state.rst
@@ -28,10 +28,10 @@
 ..
 .. =============================================================================>
 
-encode_state_of
+encode_state
 ===============
 
-.. doxygenclass:: ztd::text::encode_state_of
+.. doxygenclass:: ztd::text::encode_state
 	:members:
 
-.. doxygentypedef:: ztd::text::encode_state_of_t
+.. doxygentypedef:: ztd::text::encode_state_t
diff --git a/documentation/source/api/encodings/cuneicode_encoding.rst b/documentation/source/api/encodings/cuneicode_encoding.rst
@@ -28,11 +28,15 @@
 ..
 .. =============================================================================>
 
-cuneicode_encoding
-==================
+🔨 cuneicode_encoding (In Progress)
+===================================
+
+.. warning::
+
+	|unfinished_warning|
 
 This encoding is only available if the :ref:`configuration macro for ZTD_TEXT_USE_CUNEICODE <config-ZTD_TEXT_USE_CUNEICODE>` is turned on.
 
 This encoding is tied to the `cuneicode library <https://ztdcuneicode.rtfd.io>`_. The cuneicode library is a C library for validation, counting, and transcoding between a fixed set of encodings, with an additional plug for arbitrary encodings that can be added at run-time. This is in opposition to :doc:`iconv </api/encodings/iconv_encoding>`, where additional encodings can only be added by-hand through recompiling the code or hooking specific system configuration points.
 
-cuneicode has a variable number of encodings it can be compiled with to support. States are pre-constructed in the encoding itself and copied as necessary when ``encode_state_of`` or ``decode_state_of``\ s are being created to call the desired conversion functions. The user can inspect the output error parameter from the ``cuneicode_encoding`` constructor to know of failure, or not pass in the output error parameter and instead take one of a assert, thrown exception, or ``abort`` (preferred invocation in that order).
+cuneicode has a variable number of encodings it can be compiled with to support. States are pre-constructed in the encoding itself and copied as necessary when ``encode_state`` or ``decode_state``\ s are being created to call the desired conversion functions. The user can inspect the output error parameter from the ``cuneicode_encoding`` constructor to know of failure, or not pass in the output error parameter and instead take one of a assert, thrown exception, or ``abort`` (preferred invocation in that order).
diff --git a/documentation/source/api/encodings/iconv_encoding.rst b/documentation/source/api/encodings/iconv_encoding.rst
@@ -28,11 +28,15 @@
 ..
 .. =============================================================================>
 
-iconv_encoding
-==============
+🔨 iconv_encoding (In Progress)
+===============================
+
+.. warning::
+
+	|unfinished_warning|
 
 This encoding is only available if the :ref:`configuration macro for ZTD_TEXT_USE_ICONV <config-ZTD_TEXT_USE_ICONV>` is turned on.
 
 This encoding is tied to the `iconv library <https://www.gnu.org/software/libiconv/>`_. It will attempt to bootstrap iconv on first use of the encoding through use of ``GetProcAddress``/``dlsym`` and friends. If it cannot find it will either assert, abort, or loudly annoy the user in some way. The code is retrieved dynamically, as iconv is under a LGPL/GPL licensed and cannot be traditionally built / statically linked with application code (though in the future we may provide a way for software to do that if the software being made with this library is also GPL-compatible software).
 
-iconv has a fixed set of encodings it can be compiled with to support. States are pre-constructed in the encoding itself and copied as necessary when ``encode_state_of`` or ``decode_state_of``\ s are being created to call the iconv functions. The user can inspect the output error parameter from the ``iconv_encoding`` constructor to know of failure, or not pass in the output error parameter and instead take one of a assert, thrown exception, or ``abort`` (preferred invocation in that order).
+iconv has a fixed set of encodings it can be compiled with to support. States are pre-constructed in the encoding itself and copied as necessary when ``encode_state`` or ``decode_state``\ s are being created to call the iconv functions. The user can inspect the output error parameter from the ``iconv_encoding`` constructor to know of failure, or not pass in the output error parameter and instead take one of a assert, thrown exception, or ``abort`` (preferred invocation in that order).
diff --git a/documentation/source/api/encodings/literal.rst b/documentation/source/api/encodings/literal.rst
@@ -39,7 +39,7 @@ If you know the encoding of literals for your project (you provide the command l
 
 If the library does not recognize the encoding and cannot transcode it properly, it will also loudly warn you that it does not understand the encoding of the literal (in which case, file an issue about it and we will add it to the list of acceptable literal encodings).
 
-If you like to live dangerously and do not care for the warnings, you can define :ref:`a configuration macro named ZTD_TEXT_YES_PLEASE_FUCK_MY_LITERALS_UP_I_MEAN_IT <config-ZTD_TEXT_YES_PLEASE_FUCK_MY_LITERALS_UP_I_MEAN_IT>` and it will just blindly go with whatever weird default it ended up deciding on.
+If you like to live dangerously and do not care for the warnings, you can define :ref:`a configuration macro named ZTD_TEXT_YES_PLEASE_DESTROY_MY_LITERALS_UTTERLY_I_MEAN_IT <config-ZTD_TEXT_YES_PLEASE_DESTROY_MY_LITERALS_UTTERLY_I_MEAN_IT>` and it will just blindly go with whatever weird default it ended up deciding on.
 
 (This is usually a catastrophically terrible idea, but let is not be said that we didn't give you the power to do great things, even if it cost you your foot.)
 

diff --git a/documentation/source/api/encodings/wide_literal.rst b/documentation/source/api/encodings/wide_literal.rst
@@ -39,7 +39,7 @@ If you know the encoding of wide literals for your project (you provide the comm
 
 If the library does not recognize the encoding and cannot transcode it properly, it will also loudly warn you that it does not understand the encoding of the literal (in which case, file an issue about it and we will add it to the list of acceptable wide literal encodings).
 
-If you like to live dangerously and do not care for the warnings, you can define :ref:`a configuration macro named ZTD_TEXT_YES_PLEASE_FUCK_MY_WIDE_LITERALS_UP_I_MEAN_IT <config-ZTD_TEXT_YES_PLEASE_FUCK_MY_WIDE_LITERALS_UP_I_MEAN_IT>` and it will just blindly go with whatever weird default it ended up deciding on.
+If you like to live dangerously and do not care for the warnings, you can define :ref:`a configuration macro named ZTD_TEXT_YES_PLEASE_DESTROY_MY_WIDE_LITERALS_UTTERLY_I_MEAN_IT <config-ZTD_TEXT_YES_PLEASE_DESTROY_MY_WIDE_LITERALS_UTTERLY_I_MEAN_IT>` and it will just blindly go with whatever weird default it ended up deciding on.
 
 (This is usually a catastrophically terrible idea, but let is not be said that we didn't give you the power to do great things, even if it cost you your foot.)
 

diff --git a/documentation/source/api/error handlers/assume_valid_handler.rst b/documentation/source/api/error handlers/assume_valid_handler.rst
@@ -31,7 +31,7 @@
 assume_valid_handler
 ====================
 
-The ``assume_valid_handler`` is a Undefined-Behavior invoking error handler. If an error is encountered, the encoding can legally ignore and never, ever call the error handler at all. This can invoke ☢️☢️Undefined Behavior☢️☢️ on malformed input.
+The ``assume_valid_handler`` is a Undefined-Behavior invoking error handler. If an error is encountered, the encoding can legally ignore and never, ever call the error handler at all. This can invoke |ub| on malformed input.
 
 .. warning
 

diff --git a/documentation/source/api/is_transcoding_compatible.rst b/documentation/source/api/is_transcoding_compatible.rst
@@ -0,0 +1,58 @@
+.. =============================================================================
+..
+.. 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.
+..
+.. =============================================================================>
+
+is_transcoding_compatible/is_bitwise_transcoding_compatible
+===========================================================
+
+This classification checks if two encodings are compatible, or bitwise compatible. The heuristic for normal compatibility is simple:
+
+- it checks if the two encodings are identical;
+- it checks if the two encodings are near-identical derivations of one another (e.g., :doc:`UTF-8 </api/encodings/utf8>` being converted to :doc:`MUTF-8 </api/encodings/mutf8>` (but not in the other direction)); or,
+- it checks if the code point types between the two encodings are the same, or if they are :doc:`both some form of unicode code point </api/is_unicode_code_point>`.
+
+This type specifically uses the first type as the ``From`` encoding (e.g., the one to decode the input code unit sequence) and the second type as the ``To`` encoding (e.g., the one to encode the intermediate decoded code point sequence).
+
+.. note::
+
+	|specializations_okay|
+
+.. warning::
+
+	Specializing this type for types which are not either transcoding compatible or bitwise compatible can result in |ub| within the library.
+
+.. doxygenclass:: ztd::text::is_transcoding_compatible
+	:members:
+
+.. doxygenvariable:: ztd::text::is_transcoding_compatible_v
+
+.. doxygenclass:: ztd::text::is_bitwise_transcoding_compatible
+	:members:
+
+.. doxygenvariable:: ztd::text::is_bitwise_transcoding_compatible_v
diff --git a/documentation/source/api/is_unicode_code_point.rst b/documentation/source/api/is_unicode_code_point.rst
@@ -39,7 +39,7 @@ This checks if the provided type is a :doc:`unicode_code_point </api/unicode_cod
 
 .. warning::
 
-	Note there are some :term:`expectations of unicode code points <unicode code point>`. If your type violates these expectations then code depending on them is free to execute ☢️☢️Undefined Behavior☢️☢️.
+	Note there are some :term:`expectations of unicode code points <unicode code point>`. If your type violates these expectations then code depending on them is free to execute |ub|.
 
 .. doxygenclass:: ztd::text::is_unicode_code_point
 	:members:

diff --git a/documentation/source/api/is_unicode_scalar_value.rst b/documentation/source/api/is_unicode_scalar_value.rst
@@ -39,7 +39,7 @@ This checks if the provided type is a :doc:`unicode_scalar_value </api/unicode_s
 
 .. warning::
 
-	Note there are some :term:`expectations of scalar value types <unicode scalar value>`. If your type violates these expectations then code depending on them is free to execute ☢️☢️Undefined Behavior☢️☢️.
+	Note there are some :term:`expectations of scalar value types <unicode scalar value>`. If your type violates these expectations then code depending on them is free to execute |ub|.
 
 .. doxygenclass:: ztd::text::is_unicode_scalar_value
 	:members:

diff --git a/documentation/source/api/max_code_points.rst b/documentation/source/api/max_code_points.rst
@@ -35,7 +35,7 @@ The maximum number of code points needed for a given encoding object. This can b
 
 .. code-block:: cpp
 
-	using code_point = ztd::text::code_point_of_t<ztd::text::utf8>;
+	using code_point = ztd::text::code_point_t<ztd::text::utf8>;
 	constexpr std::size_t max_output_size = ztd::text::max_code_points_v<ztd::text::utf8>;
 	
 	std::array<code_point, max_output_size> my_cxx_buffer;

diff --git a/documentation/source/api/max_code_units.rst b/documentation/source/api/max_code_units.rst
@@ -35,7 +35,7 @@ The maximum number of code units needed for a given encoding object. This can be
 
 .. code-block:: cpp
 
-	using code_unit = ztd::text::code_unit_of_t<ztd::text::utf8>;
+	using code_unit = ztd::text::code_unit_t<ztd::text::utf8>;
 	constexpr std::size_t max_output_size = ztd::text::max_code_units_v<ztd::text::utf8>;
 	
 	std::array<code_unit, max_output_size> my_cxx_buffer;

diff --git a/documentation/source/api/unicode_code_point.rst b/documentation/source/api/unicode_code_point.rst
@@ -40,9 +40,9 @@ A unicode code point is stored as an at least 32-bit value, but may occupy more
 Internal Type
 -------------
 
-.. note::
+.. warning::
 
-	Names with double underscores are reserved for the implementation. Referencing this class directly is bad, and the name can be changed at any point in the future.
+	|reserved_name|
 
 .. doxygenclass:: ztd::text::__impl::__unicode_code_point
 	:members: