extend docmentation of core

docs/api/core/bitcast.rst

@@ -0,0 +1,17 @@
+Bit Cast
+========
+
+**Header** ``aarith/core/bit_cast.hpp``
+
+Unfortunately, there is no easy way to completely re-interpret bits as a different type. There is
+`the usual <https://en.wikipedia.org/wiki/Type_punning#Use_of_union>`_ trick
+of using an union. This is undefined behavior. This is why we opted to use the solution
+`from this talk <https://www.youtube.com/watch?v=_qzMpk-22cc>`_.
+
+In the near future, when C++20 is more widely availabe, we will switch to using
+`std::bit_cast <https://en.cppreference.com/w/cpp/numeric/bit_cast>`_
+
+
+
+
+.. doxygenfile:: bit_cast.hpp

docs/api/core/stringnum.rst

@@ -0,0 +1,20 @@
+String and Number Utilities
+===========================
+
+This is a collection of the most basic string and number utilities that are used throughout aarith.
+
+String Utilities
+----------------
+
+**Header** ``aarith/core/core_string_utils``
+
+.. doxygenfile:: core_string_utils.hpp
+
+
+Number Utilities
+----------------
+
+**Header** ``aarith/core/core_number_utils.hpp``
+
+.. doxygenfile:: core_number_utils.hpp
+

docs/index.rst

@@ -12,7 +12,8 @@ Aarith currently supports
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :caption: General
 
    installation
    tutorial
@@ -22,13 +23,13 @@ Aarith currently supports
 
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
     :caption: Integers
 
     api/integer
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
     :caption: Floating-Point Numbers
 
     api/float/class
@@ -37,11 +38,6 @@ Aarith currently supports
     api/float/utilities
 
 
-.. toctree::
-    :maxdepth: 2
-    :caption: Utilities
-
-    api/word_array
 
 Publication
 -----------
@@ -67,6 +63,16 @@ Bibtex:
 
 
 
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Core & Utilities
+
+    api/core/word_array
+    api/core/stringnum
+    api/core/traits
+    api/core/bitcast
+
 Indices and tables
 ==================
 

examples/float_sci_str.cpp

@@ -1,5 +1,5 @@
 #include <aarith/float.hpp>
-#include <aarith/float/string_utils.hpp>
+#include <aarith/float/float_string_utils.hpp>
 #include <bitset>
 #include <cmath>
 #include <sstream>

src/aarith/core.hpp

@@ -10,7 +10,7 @@
 
 #include <aarith/core/traits.hpp>
 
-#include <aarith/core/number_utils.hpp>
-#include <aarith/core/string_utils.hpp>
+#include <aarith/core/core_number_utils.hpp>
+#include <aarith/core/core_string_utils.hpp>
 
 #include <aarith/core/word_array_random_generation.hpp>

src/aarith/core/number_utils.hpp → src/aarith/core/core_number_utils.hpp

@@ -2,18 +2,47 @@
 
 namespace aarith {
 
-template <unsigned Radix, unsigned Value> constexpr double log();
+/**
+ * @brief Constexpr version of log
+ *
+ * This method is necessary as not all compilers already come with a constexpr ready math library.
+ *
+ * @note Only two values needed by aarith are epxlictly stored!
+ *
+ * @tparam Base The base of the loarithm
+ * @tparam Value The value whose logarithm is to be computed
+ * @return The logarithm of Value base Base
+ */
+template <unsigned Base, unsigned Value> constexpr double log();
+
 
-template <> constexpr double log<2, 10>()
+/**
+ * @brief The constexpr value of log_2(10)
+ * @return log_2(10)
+ */
+template <> constexpr double log<2, 10>() // NOLINT
 {
-    return 3.32192809489;
+    return 3.32192809489; // NOLINT
 }
 
-template <> constexpr double log<10, 2>()
+/**
+ * @brief The constexpr value of log_10(2)
+ * @return log_10(2)
+ */
+template <> constexpr double log<10, 2>() // NOLINT
 {
-    return 0.30102999566;
+    return 0.30102999566; // NOLINT
 }
 
+/**
+ * @brief Constexpr version of the ceil operation
+ *
+ * This method is only necessary as not all compilers already have an constexpr ready math library.
+ *
+ * @tparam Result Type for the result
+ * @param num The number to round down
+ * @return num rounded down
+ */
 template <class Result> constexpr Result ceil(double num)
 {
     return (static_cast<double>(static_cast<Result>(num)) == num)
@@ -74,10 +103,10 @@ constexpr size_t pow(const size_t base, const size_t exponent)
 {
     size_t first_bit = 0UL;
     size_t tmp = n;
-    while (tmp)
+    while (tmp > 0)
     {
         ++first_bit;
-        tmp = tmp >> 1;
+        tmp = tmp >> 1U;
     }
     return first_bit;
 }

src/aarith/core/string_utils.hpp → src/aarith/core/core_string_utils.hpp

@@ -4,13 +4,26 @@
 
 namespace aarith {
 
+/**
+ * @brief
+ * @param bits
+ * @return
+ */
 inline constexpr auto number_of_decimal_digits(size_t bits) -> size_t
 {
     // When converted to decimal, an n-bit binary numeral will have at most k*n decimal digits,
     // rounded up, where k = log_10 2 ~ 0.301.
     return (bits * 301) / 1000 + ((bits * 301) % 1000 == 0 ? 0 : 1); // NOLINT
 }
 
+/**
+ * @brief
+ * @tparam T
+ * @tparam U
+ * @param dividend
+ * @param divisor
+ * @return
+ */
 template <class T, class U>
 constexpr auto rounded_integer_division(T dividend, U divisor) -> decltype(T{} / U{})
 {
@@ -94,6 +107,12 @@ auto to_binary(const word_array<Width, WordType>& value) -> std::string
     return result;
 }
 
+/**
+ * @brief Outputs a `word_array` to an output stream using the convenient << operator form
+ * @tparam W Width of the word array
+ * @tparam WordType The type used to store the actual data
+ * @tparam WA Generic word array type
+ */
 template <size_t W, typename WordType, template <size_t, typename> class WA,
           typename =
               std::enable_if_t<is_word_array_v<WA<W, WordType>> && !is_integral_v<WA<W, WordType>>>>

src/aarith/core/traits.hpp

@@ -6,12 +6,26 @@
 
 namespace aarith {
 
+/**
+ * @brief Type trait to check if a type is a word array
+ *
+ * @see `word_array`
+ *
+ * @tparam Type The type to check
+ */
 template <class Type> class is_word_array
 {
 public:
+    /**
+     * By default, no type is an aarith word array
+     */
     static constexpr bool value = false;
 };
 
+/**
+ *
+ * @tparam Type
+ */
 template <class Type> inline constexpr bool is_word_array_v = is_word_array<Type>::value;
 
 template <class Type> class is_integral
@@ -38,21 +52,55 @@ template <class Type> class is_signed
 
 template <class Type> inline constexpr bool is_signed_v = is_signed<Type>::value;
 
+/**
+ * @brief Type trait to check if a type is an aarith floating_point number
+ *
+ * @note This does *not* return true for the native data types such as float or double!
+ *
+ * @tparam Type The type to check
+ */
 template <class Type> class is_float
 {
 public:
+
+    /**
+     * By default, a type is not of type aarith floating_point
+     */
     static constexpr bool value = false;
 };
 
+/**
+ * @brief Tests if a type is an aarith floating_point
+ *
+ * Helper for the `is_float` type trait
+ *
+ * @tparam Type The type to check for being an aarith `floating_point`
+ */
 template <class Type> inline constexpr bool is_float_v = is_float<Type>::value;
 
+/**
+ * @brief Type trait to check if two types use the same word type to store the data
+ *
+ * @tparam A First type
+ * @tparam B Second type
+ */
 template <typename A, typename B>
 inline constexpr bool same_word_type = std::is_same_v<typename A::word_type, typename B::word_type>;
 
+/**
+ * @brief Type trait to check if two types have the same 'signedness'
+ *
+ * It returns true if and only if both types are signed or unsigned
+ *
+ * @tparam A First type
+ * @tparam B Second type
+ */
 template <typename A, typename B>
 inline constexpr bool same_signedness = (is_unsigned_v<A> == is_unsigned_v<B>);
 
 /**
+ * @brief Type trait to check a type for being an unsigned integer
+ *
  * It seems that the type traits of C++ have no reasonable concept of "unsigned integer" so we have
  * to add this ourselves.
  *

src/aarith/float/string_utils.hpp → src/aarith/float/float_string_utils.hpp

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <aarith/core/string_utils.hpp>
+#include <aarith/core/core_string_utils.hpp>
 
 #include <sstream>
 

src/aarith/float_no_operators.hpp

@@ -3,8 +3,8 @@
 #include <aarith/float/float_comparisons.hpp>
 #include <aarith/float/float_operations.hpp>
 #include <aarith/float/float_random_generation.hpp>
+#include <aarith/float/float_string_utils.hpp>
 #include <aarith/float/float_utils.hpp>
 #include <aarith/float/floating_point.hpp>
 #include <aarith/float/nan_payload.hpp>
-#include <aarith/float/string_utils.hpp>
 #include <aarith/float/total_order.hpp>

src/aarith/integer/string_utils.hpp → src/aarith/integer/integer_string_utils.hpp

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <aarith/core/string_utils.hpp>
+#include <aarith/core/core_string_utils.hpp>
 
 namespace aarith {
 

src/aarith/integer/integers.hpp

@@ -341,7 +341,7 @@ template <size_t Width, typename WordType> class is_word_array<integer<Width, Wo
 
 } // namespace aarith
 
-#include <aarith/core/number_utils.hpp>
+#include <aarith/core/core_number_utils.hpp>
 
 // We are only allowed to extend std with specializations
 // https://en.cppreference.com/w/cpp/language/extending_std

src/aarith/integer_no_operators.hpp

@@ -8,6 +8,6 @@
 #include <aarith/integer/integer_ranges.hpp>
 #include <aarith/integer/integers.hpp>
 
-#include <aarith/integer/string_utils.hpp>
+#include <aarith/integer/integer_string_utils.hpp>
 
 #include <aarith/integer/integer_random_generation.hpp>

tests/CMakeLists.txt

@@ -28,7 +28,7 @@ add_aarith_test(integer-cast FILES integer/integer-casts.cpp)
 add_aarith_test(float-anytime-operations FILES float/anytime_operations-float-test.cpp)
 add_aarith_test(float FILES float/float-test.cpp  float/float_general_operations.cpp)
 add_aarith_test(float-casts FILES float/float_casts.cpp)
-add_aarith_test(float-string_utils FILES float/string_utils.cpp)
+add_aarith_test(float-string_utils FILES float/integer_string_utils.cpp)
 add_aarith_test(float-comparison FILES float/float_comparisons.cpp)
 add_aarith_test(float-total_ordering FILES float/total_ordering.cpp)
 add_aarith_test(float-sign_bit_operations FILES float/sign_bit_operations.cpp)

tests/core/bit_operations-test.cpp

@@ -1,7 +1,7 @@
 #include <catch.hpp>
 
 #include <aarith/core.hpp>
-#include <aarith/core/string_utils.hpp>
+#include <aarith/core/core_string_utils.hpp>
 
 #include "../test-signature-ranges.hpp"
 #include "gen_word_array.hpp"

tests/core/word_array-extraction-test.cpp

@@ -3,7 +3,7 @@
 #include "../test-signature-ranges.hpp"
 #include "gen_word_array.hpp"
 #include <aarith/core.hpp>
-#include <aarith/core/string_utils.hpp>
+#include <aarith/core/core_string_utils.hpp>
 
 using namespace aarith;
 

tests/core/word_array-utility-test.cpp

@@ -3,7 +3,7 @@
 #include "../test-signature-ranges.hpp"
 #include "gen_word_array.hpp"
 #include <aarith/core.hpp>
-#include <aarith/core/string_utils.hpp>
+#include <aarith/core/core_string_utils.hpp>
 
 using namespace aarith;