📝 Documentation for much of the new C APIs!

soasis · Nov 14, 2021 · 33ca6e5 · 33ca6e5
1 parent c25987d
commit 33ca6e5
Show file tree

Hide file tree

Showing 22 changed files with 955 additions and 205 deletions.
diff --git a/documentation/source/api/alignment.rst b/documentation/source/api/alignment.rst
@@ -0,0 +1,34 @@
+.. =============================================================================
+..
+.. ztd.idk
+.. Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+.. Contact: opensource@soasis.org
+..
+.. Commercial License Usage
+.. Licensees holding valid commercial ztd.idk 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
+..
+.. 		https://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.
+..
+.. =============================================================================>
+
+Alignment
+=========
+
+This API is identical to the one defined in the C APIs, which can be :doc:`found here</c_api/alignment>`.
diff --git a/documentation/source/api/endian.rst b/documentation/source/api/endian.rst
@@ -31,6 +31,8 @@
 endian
 ======
 
-The endian enumeration is a very simple enum used to communicate what kind of byte ordering certain parts of the library should use to interpret incoming byte sequences.
+The endian enumeration is a very simple ``enum class`` used to communicate what kind of byte ordering certain parts of the library should use to interpret incoming byte sequences. The C version uses macros and can be found :doc:`here </c_api/endian>`.
+
+The values are ``ztd::endian::little``, ``ztd::endian::big``, or ``ztd::endian::native``.
 
 .. doxygentypedef:: ztd::endian
diff --git a/documentation/source/c_api/alignment.rst b/documentation/source/c_api/alignment.rst
@@ -0,0 +1,36 @@
+.. =============================================================================
+..
+.. ztd.idk
+.. Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+.. Contact: opensource@soasis.org
+..
+.. Commercial License Usage
+.. Licensees holding valid commercial ztd.idk 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
+..
+.. 		https://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.
+..
+.. =============================================================================>
+
+Alignment
+=========
+
+These APIs aid in aligning pointers and types. They are typically available for both C and C++.
+
+.. doxygendefine:: ZTD_ASSUME_ALIGNED
diff --git a/documentation/source/c_api/assert.rst b/documentation/source/c_api/assert.rst
@@ -28,7 +28,7 @@
 ..
 .. =============================================================================>
 
-assertions
+Assertions
 ==========
 
 This API defines 2 assertion macros. One is named ``ZTD_ASSERT``, and the other is named ``ZTD_ASSERT_MESSAGE``. The first takes only one or more conditional tokens, the second takes a mandatory message token as the first parameter, and then one or more conditional parameters.

diff --git a/documentation/source/c_api/bit.intrinsic.rst b/documentation/source/c_api/bit.intrinsic.rst
@@ -0,0 +1,68 @@
+.. =============================================================================
+..
+.. ztd.idk
+.. Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+.. Contact: opensource@soasis.org
+..
+.. Commercial License Usage
+.. Licensees holding valid commercial ztd.idk 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
+..
+.. 		https://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.
+..
+.. =============================================================================>
+
+Bit Intrinsics
+==============
+
+Bit intrinsics are functions that map as closely as possible to behavior and functionality in ISAs without needing to deal with the undefined behavior and non-portability of said architectures. It provides vital functionality that can greatly speed up work on specific kinds of bit operations. The provided intrinsics here are a large subset of the most efficient operations, offered in various flavors for ease-of-use.
+
+"Leading" refers to the most significant bit in a given value. This is the "left side" of an integer when writing source code, such that ``0b10`` has a most significant bit of ``1``. "Trailing" refers to the least significant bit in a given value. This is the "left side" of an integer when writing source code, such that ``0b10`` has a least significant bit of ``0``.
+
+.. doxygendefine:: ztdc_count_ones
+
+.. doxygendefine:: ztdc_count_zeros
+
+.. doxygendefine:: ztdc_count_leading_zeros
+
+.. doxygendefine:: ztdc_count_trailing_zeros
+
+.. doxygendefine:: ztdc_count_leading_ones
+
+.. doxygendefine:: ztdc_count_trailing_ones
+
+.. doxygendefine:: ztdc_first_leading_zero
+
+.. doxygendefine:: ztdc_first_trailing_zero
+
+.. doxygendefine:: ztdc_first_leading_one
+
+.. doxygendefine:: ztdc_first_trailing_one
+
+.. doxygendefine:: ztdc_rotate_left
+
+.. doxygendefine:: ztdc_rotate_right
+
+.. doxygendefine:: ztdc_has_single_bit
+
+.. doxygendefine:: ztdc_bit_width
+
+.. doxygendefine:: ztdc_bit_ceil
+
+.. doxygendefine:: ztdc_bit_floor
diff --git a/documentation/source/c_api/bit.memreverse.rst b/documentation/source/c_api/bit.memreverse.rst
@@ -0,0 +1,36 @@
+.. =============================================================================
+..
+.. ztd.idk
+.. Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+.. Contact: opensource@soasis.org
+..
+.. Commercial License Usage
+.. Licensees holding valid commercial ztd.idk 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
+..
+.. 		https://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.
+..
+.. =============================================================================>
+
+8-bit Memory Reverse
+====================
+
+.. doxygenfunction:: ztdc_memreverse8
+
+.. doxygenfunction:: ztdc_memreverse8uN
diff --git a/documentation/source/c_api/bit.store_load.rst b/documentation/source/c_api/bit.store_load.rst
@@ -0,0 +1,58 @@
+.. =============================================================================
+..
+.. ztd.idk
+.. Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+.. Contact: opensource@soasis.org
+..
+.. Commercial License Usage
+.. Licensees holding valid commercial ztd.idk 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
+..
+.. 		https://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.
+..
+.. =============================================================================>
+
+8-bit Endian Load/Store
+=======================
+
+
+Unsigned Variants
+-----------------
+
+.. doxygenfunction:: ztdc_store8_leuN
+.. doxygenfunction:: ztdc_store8_beuN
+.. doxygenfunction:: ztdc_load8_leuN
+.. doxygenfunction:: ztdc_load8_beuN
+.. doxygenfunction:: ztdc_store8_aligned_leuN
+.. doxygenfunction:: ztdc_store8_aligned_beuN
+.. doxygenfunction:: ztdc_load8_aligned_leuN
+.. doxygenfunction:: ztdc_load8_aligned_beuN
+
+Signed Variants
+---------------
+
+.. doxygenfunction:: ztdc_store8_lesN
+.. doxygenfunction:: ztdc_store8_besN
+.. doxygenfunction:: ztdc_load8_lesN
+.. doxygenfunction:: ztdc_load8_besN
+.. doxygenfunction:: ztdc_store8_aligned_lesN
+.. doxygenfunction:: ztdc_store8_aligned_besN
+.. doxygenfunction:: ztdc_load8_aligned_lesN
+.. doxygenfunction:: ztdc_load8_aligned_besN
+
diff --git a/documentation/source/c_api/endian.rst b/documentation/source/c_api/endian.rst
@@ -0,0 +1,40 @@
+.. =============================================================================
+..
+.. ztd.idk
+.. Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+.. Contact: opensource@soasis.org
+..
+.. Commercial License Usage
+.. Licensees holding valid commercial ztd.idk 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
+..
+.. 		https://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.
+..
+.. =============================================================================>
+
+endian
+======
+
+The endian enumeration is a very simple enum used to communicate what kind of byte ordering certain parts of the library should use to interpret incoming byte sequences. The C version uses macros and can be found :doc:`here </c_api/endian>`.
+
+.. doxygendefine:: ZTDC_LITTLE_ENDIAN
+
+.. doxygendefine:: ZTDC_BIG_ENDIAN
+
+.. doxygendefine:: ZTDC_NATIVE_ENDIAN
diff --git a/documentation/source/c_api/extent.rst b/documentation/source/c_api/extent.rst
@@ -0,0 +1,36 @@
+.. =============================================================================
+..
+.. ztd.idk
+.. Copyright © 2021 JeanHeyd "ThePhD" Meneide and Shepherd's Oasis, LLC
+.. Contact: opensource@soasis.org
+..
+.. Commercial License Usage
+.. Licensees holding valid commercial ztd.idk 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
+..
+.. 		https://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.
+..
+.. =============================================================================>
+
+Extent
+======
+
+These utilities are for handling extents (arrays and pointers) in C and C++.
+
+.. doxygendefine:: ZTD_PTR_EXTENT
diff --git a/include/ztd/idk/assert.h b/include/ztd/idk/assert.h
@@ -130,9 +130,9 @@
 /// @param[in] ... The conditional expressions to check against.
 ///
 /// @remarks The conditions must result in a value that is convertible to a boolean in a boolean context. This macro
-/// does nothing when ZTD_DEBUG is not detected. (It will still (void)-cast the used items, to prevent unused warnings.)
-/// If the condition is not reached, this function will perform either a user-defined action or terminate/exit (not
-/// abort).
+/// does nothing when `ZTD_DEBUG` is not detected. (It will still (void)-cast the used items, to prevent unused
+/// warnings.) If the condition is not reached, this function will perform either a user-defined action or
+/// terminate/exit (not abort).
 //////
 #define ZTD_ASSERT(...) ZTD_ASSERT_I_(__VA_ARGS__)
 
@@ -143,9 +143,9 @@
 /// @param[in] ... The conditional expressions to check against.
 ///
 /// @remarks The conditions must result in a value that is convertible to a boolean in a boolean context. This macro
-/// does nothing when ZTD_DEBUG is not detected. (It will still (void)-cast the used items, to prevent unused warnings.)
-/// If the condition is not reached, this function will perform either a user-defined action or terminate/exit (not
-/// abort).
+/// does nothing when `ZTD_DEBUG` is not detected. (It will still (void)-cast the used items, to prevent unused
+/// warnings.) If the condition is not reached, this function will perform either a user-defined action or
+/// terminate/exit (not abort).
 //////
 #define ZTD_ASSERT_MESSAGE(_MESSAGE, ...) ZTD_ASSERT_MESSAGE_I_(_MESSAGE, __VA_ARGS__)
 

diff --git a/include/ztd/idk/assume_aligned.h b/include/ztd/idk/assume_aligned.h
@@ -60,4 +60,30 @@
 #endif
 // clang-format on
 
+//////
+/// @addtogroup ztd_idk_assume_aligned Assume Aligned
+///
+/// @{
+//////
+
+//////
+/// @def ZTD_ASSUME_ALIGNED(_ALIGNMENT, ...)
+///
+/// @brief Returns a pointer suitable-aligned for `_ALIGNMENT`.
+///
+/// @param[in] _ALIGNMENT An integer constant expression indicating the alignment of the pointer value.
+/// @param[in] ... The pointer to assume alignment of.
+///
+/// @returns A pointer (assumed to be) suitably-aligned to `_ALIGNMENT`.
+///
+/// @remarks This function does NOT align the pointer, just marks it as such. This uses builtins or other tricks
+/// depending on the compiler. It can trigger Undefined Behavior if it is not properly checked and protected against, so
+/// make sure the pointer is properly aligned.
+//////
+
+//////
+/// @}
+//////
+
+
 #endif // ZTD_IDK_ASSUME_ALIGNED_H