From 225ec192c5c7cdc73a572696a812f755a7814efb Mon Sep 17 00:00:00 2001
From: _xeroxz <xerox@back.engineering>
Date: Thu, 24 Jun 2021 00:21:44 -0700
Subject: [PATCH] added some documentation, also added @CompiledCode
 generate_random_number...

---
 include/lloutils.hpp | 68 ++++++++++++++++++++++++++++++++++++--------
 1 file changed, 56 insertions(+), 12 deletions(-)

diff --git a/include/lloutils.hpp b/include/lloutils.hpp
index 37857f3..3375282 100644
--- a/include/lloutils.hpp
+++ b/include/lloutils.hpp
@@ -7,52 +7,96 @@
 
 namespace llo::utils
 {
+    /// <summary>
+    /// generates a random number of a specific type...
+    /// </summary>
+    /// <typeparam name="number_t">type of number to generate... must be arithemtic...</typeparam>
+    /// <param name="minimum">the minimum that can be generated...</param>
+    /// <param name="maximum">the maximum that can be generated...</param>
+    /// <returns>returns random arithemtic number...</returns>
     template < class number_t > number_t generate_random_number( const number_t minimum, const number_t maximum )
     {
         static_assert( std::is_arithmetic_v< number_t >, "type is not arithmetic..." );
 
-        std::random_device rd;
-        std::mt19937 mt( rd() );
-        std::uniform_real_distribution< double > dist( minimum, maximum );
-        return dist( mt );
+        using uniform_distribution_t =
+            std::conditional_t< std::is_integral_v< number_t >, std::uniform_int_distribution< number_t >,
+                                std::uniform_real_distribution< number_t > >;
+
+        std::random_device random_device;
+        auto mt = std::mt19937{ random_device() };
+        auto uniform_distribution = uniform_distribution_t{ minimum, maximum };
+        return uniform_distribution( mt );
     }
 
+    /// <summary>
+    /// hash class, used in lloiff, symbols, sections, and much more...
+    /// </summary>
+    /// <typeparam name="T"></typeparam>
     template < class T > class hash_t
     {
-        std::size_t hash_result;
+        std::size_t unique_hash, data_hash;
         const T data;
 
       public:
-        hash_t()
-        {
-        }
-
+        /// <summary>
+        /// hash constructor which generates the hash...
+        /// </summary>
+        /// <param name="data">data to be hashed...</param>
         hash_t( const T &data ) : data{ data }
         {
             auto random_num =
                 llo::utils::generate_random_number< std::uint64_t >( 0, std::numeric_limits< std::uint64_t >::max() );
 
-            this->hash_result = std::hash< T >{}( data ) + std::hash< std::uint64_t >{}( random_num );
+            this->unique_hash = std::hash< T >{}( data ) + std::hash< std::uint64_t >{}( random_num );
+            this->data_hash = std::hash< T >{}( data );
         }
 
+        /// <summary>
+        /// makes a shared pointer containing the hash object... useful when chaining....
+        /// </summary>
+        /// <param name="data">data to be hashed...</param>
+        /// <returns>shared pointer of the hash object....</returns>
         static std::shared_ptr< hash_t > make( const T &data )
         {
             return std::make_shared< hash_t >( data );
         }
 
+        /// <summary>
+        /// returns a copy of the underlying data...
+        /// </summary>
+        /// <returns>returns a copy of the hashed data...</returns>
         T get_data() const
         {
             return data;
         }
 
+        /// <summary>
+        /// get the hash of the data... this hash is the same across each run...
+        /// </summary>
+        /// <returns>returns the constant hash value for the data...</returns>
         std::size_t get_hash() const
         {
-            return hash_result;
+            return data_hash;
+        }
+
+        /// <summary>
+        /// returns a unique, per-runtime, per-object hash of the data...
+        /// useful when there are multiple objects with the same data...
+        /// </summary>
+        /// <returns>returns the unique hash...</returns>
+        std::size_t get_unique_hash() const
+        {
+            return unique_hash;
         }
 
+        /// <summary>
+        /// compares unique hashs...
+        /// </summary>
+        /// <param name="hash">const reference of a hash...</param>
+        /// <returns>returns true if both unique hashes are the same...</returns>
         bool operator==( const hash_t< T > &hash )
         {
-            return hash.has_result == this->hash_result;
+            return hash.unique_hash == this->unique_hash;
         }
     };
 } // namespace llo::utils
\ No newline at end of file