maths: document `log2` and `log2up`

maths.cpp

@@ -11,18 +11,6 @@
 #include <type_traits>
 
 
-///////////////////////////////////////////////////////////////////////////////
-template <typename T>
-T
-cruft::log2up (T v)
-{
-    return log2 ((v << 1) - 1);
-}
-
-template uint32_t cruft::log2up (uint32_t);
-template uint64_t cruft::log2up (uint64_t);
-
-
 ///////////////////////////////////////////////////////////////////////////////
 // Simple instantiations. Some functions aren't used internally to the library
 // so it's easier to instantiate early and check for broken code at library

maths.hpp

@@ -183,12 +183,18 @@ namespace cruft {
     }
 
 
-    //-----------------------------------------------------------------------------
-    // Logarithms
+    ///////////////////////////////////////////////////////////////////////////////
+    /// Calculate the base-2 logarithm of an integer, truncating to the next
+    /// lowest integer.
+    ///
+    /// `val` must be strictly greater than zero, otherwise the results are
+    /// undefined.
     template <concepts::integral T>
     constexpr T
     log2 (T val)
     {
+        assert (val > 0);
+
         T tally = 0;
         while (val >>= 1)
             ++tally;
@@ -196,10 +202,16 @@ namespace cruft {
     }
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// Calculates the base-2 logarithm of an integer, rounding up to the next
+    /// highest integer.
     template <typename T>
     T
-    log2up  (T val);
+    log2up  (T val)
+    {
+
+        return log2 ((val << 1) - 1);
+    }
 
 
     ///////////////////////////////////////////////////////////////////////////////