feat(docs): base58.hpp

README.md

@@ -12,6 +12,7 @@ c++ encoding/decoding from arbitrary base
 ## Contents
 
 - [Installation](#installation)
+- [Documentation](#documentation)
 - [Contributing](#contributing)
 
 ## Installation
@@ -42,6 +43,10 @@ And also flag for dynamic linking (if possible):
 make tools -j $(nproc) SHARED=
 ```
 
+## Documentation
+
+Available [here](https://vsek1ro.github.io/libbasen)
+
 ## Contributing
 
 Main branch is under protection rules, so you should create pull request. After merging will be runned [authors.sh](https://github.com/vSEK1RO/libbasen/blob/main/authors.sh) for adding all contributors usernames and their number of commits to [AUTHORS](https://github.com/vSEK1RO/libbasen/blob/main/AUTHORS) file.

header.html

@@ -29,11 +29,9 @@ $darkmode
 <link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
 $extrastylesheet
   <script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
-  <script type="text/javascript">
-      DoxygenAwesomeDarkModeToggle.init()
-  </script>
   <script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
   <script type="text/javascript">
+      DoxygenAwesomeDarkModeToggle.init()
       DoxygenAwesomeFragmentCopyButton.init()
   </script>
 </head>
@@ -47,6 +45,7 @@ $extrastylesheet
 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
 
 <!--BEGIN TITLEAREA-->
+<a href="https://github.com/vSEK1RO/libbasen" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill: #4779ac; color:#151513; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>
 <div id="titlearea">
 <table cellspacing="0" cellpadding="0">
  <tbody>

include/basen/base58.hpp

@@ -7,21 +7,44 @@
 
 namespace base58
 {
+    /**
+     * @brief bitcoin alphabet
+     */
     extern const char digits[59];
     extern const int8_t map[256];
 
     bool isValid(const char *str, uint64_t str_size) noexcept;
     bool isValid(std::string_view str) noexcept;
 
+    /**
+     * @throw std::overflow_error if if there is an overflow
+     */
     uint64_t sizeEncoded(std::span<const uint8_t> data) noexcept;
     uint64_t sizeDecoded(std::string_view str) noexcept;
 
-    void encode(const uint8_t *data, uint64_t data_size, char *str, uint64_t str_size) noexcept;
+    /**
+     * @return number of leading chars, which should be trimmed
+     * @warning contain leading zeros, returns count of them
+     */
+    uint64_t encode(const uint8_t *data, uint64_t data_size, char *str, uint64_t str_size) noexcept;
     std::string encode(std::span<const uint8_t> data) noexcept;
 
-    void decode(const char *str, uint64_t str_size, uint8_t *data, uint64_t data_size) noexcept;
+    /**
+     * @return number of leading chars, which should be trimmed
+     * @warning contain leading zeros, returns count of them
+     */
+    uint64_t decode(const char *str, uint64_t str_size, uint8_t *data, uint64_t data_size) noexcept;
     std::vector<uint8_t> decode(std::string_view str) noexcept;
 
+    /**
+     * @param data vector or span of data which you want to encode
+     * @return encoded string + 4 first bytes of double sha256
+     */
     std::string encodeCheck(std::span<const uint8_t> data) noexcept;
+    /**
+     * @param str string or string_view which you want to decode
+     * @return decoded data without 4 first bytes of double sha256
+     * @throw std::logic_error checksum incorrect
+     */
     std::vector<uint8_t> decodeCheck(std::string_view str);
 }

include/basen/base64.hpp

@@ -13,12 +13,25 @@ namespace base64
     bool isValid(const char *str, uint64_t str_size) noexcept;
     bool isValid(std::string_view str) noexcept;
 
+    /**
+     * @throw std::overflow_error if if there is an overflow
+     */
     uint64_t sizeEncoded(std::span<const uint8_t> data);
     uint64_t sizeDecoded(std::string_view str) noexcept;
 
+    /**
+     * @throw std::length_error if not enough allocated length
+     * @warning contain leading zeros, returns count of them
+     */
     void encode(const uint8_t *data, uint64_t data_size, char *str, uint64_t str_size);
     std::string encode(std::span<const uint8_t> data) noexcept;
 
+    /**
+     * @throw std::length_error if not enough allocated length
+     * @throw std::logic_error if out of digits map
+     * @throw std::logic_error if incorrect padding
+     * @warning contain leading zeros, returns count of them
+     */
     void decode(const char *str, uint64_t str_size, uint8_t *data, uint64_t data_size);
     std::vector<uint8_t> decode(std::string_view str) noexcept;
 }

include/basen/baseN.hpp

@@ -32,6 +32,7 @@ namespace baseN
      * @param base from 1 to 255
      * @param digits char[base] array of digits
      * @return estimated size after decoding
+     * @throw std::overflow_error if if there is an overflow
      */
     uint64_t sizeDecoded(std::string_view str, uint8_t base, const char *digits) noexcept;
 

include/basen/hash/sha256.hpp

@@ -4,9 +4,8 @@
 #include <span>
 #include <vector>
 
-#define SHA256_DIGEST_LENGTH 32
+namespace hash
-
+{
-namespace hash {
 	void sha256(const uint8_t *data, uint64_t data_size, uint8_t *hash) noexcept;
 	std::vector<uint8_t> sha256(std::span<const uint8_t> data) noexcept;
 }

include/basen/hex.hpp

@@ -13,12 +13,25 @@ namespace hex
     bool isValid(const char *str, uint64_t str_size) noexcept;
     bool isValid(std::string_view str) noexcept;
 
+    /**
+     * @throw std::overflow_error if if there is an overflow
+     */
     uint64_t sizeEncoded(std::span<const uint8_t> data);
     uint64_t sizeDecoded(std::string_view str) noexcept;
 
+    /**
+     * @throw std::length_error if not enough allocated length
+     * @warning contain leading zeros, returns count of them
+     */
     void encode(const uint8_t *data, uint64_t data_size, char *str, uint64_t str_size);
     std::string encode(std::span<const uint8_t> data) noexcept;
 
+    /**
+     * @throw std::length_error if not enough allocated length
+     * @throw std::logic_error if out of digits map
+     * @throw std::logic_error if str_size %2 != 0 (isn't hex)
+     * @warning contain leading zeros, returns count of them
+     */
     void decode(const char *str, uint64_t str_size, uint8_t *data, uint64_t data_size);
     std::vector<uint8_t> decode(std::string_view str) noexcept;
 }

src/base58.cpp

@@ -43,17 +43,17 @@ namespace base58
     {
         return baseN::sizeDecoded(str, 58, digits);
     }
-    void encode(const uint8_t *data, uint64_t data_size, char *str, uint64_t str_size) noexcept
+    uint64_t encode(const uint8_t *data, uint64_t data_size, char *str, uint64_t str_size) noexcept
     {
-        baseN::encode(data, data_size, str, str_size, 58, digits);
+        return baseN::encode(data, data_size, str, str_size, 58, digits);
     }
     std::string encode(std::span<const uint8_t> data) noexcept
     {
         return baseN::encode(data, 58, digits);
     }
-    void decode(const char *str, uint64_t str_size, uint8_t *data, uint64_t data_size) noexcept
+    uint64_t decode(const char *str, uint64_t str_size, uint8_t *data, uint64_t data_size) noexcept
     {
-        baseN::decode(str, str_size, data, data_size, 58, digits, map);
+        return baseN::decode(str, str_size, data, data_size, 58, digits, map);
     }
     std::vector<uint8_t> decode(std::string_view str) noexcept
     {

src/base64.cpp

@@ -64,7 +64,7 @@ namespace base64
     {
         if (str_size < base64::sizeEncoded(std::span<const uint8_t>(data, data_size)))
         {
-            throw std::logic_error("base64::encode: not enough allocated length");
+            throw std::length_error("base64::encode: not enough allocated length");
         }
         for (uint64_t i = 0; i < data_size / 3; i++)
         {
@@ -106,7 +106,7 @@ namespace base64
         std::string_view sv(str, str_size);
         if (data_size < base64::sizeDecoded(sv))
         {
-            throw std::logic_error("base64::decode: not enough allocated length");
+            throw std::length_error("base64::decode: not enough allocated length");
         }
         if (!base64::isValid(sv))
         {

src/hash/sha256.cpp

@@ -174,7 +174,7 @@ namespace hash
 	}
 	std::vector<uint8_t> sha256(std::span<const uint8_t> data) noexcept
 	{
-		std::vector<uint8_t> hash(SHA256_DIGEST_LENGTH);
+		std::vector<uint8_t> hash(32);
 		sha256(data.data(), data.size(), hash.data());
 		return hash;
 	}

src/hex.cpp

@@ -50,7 +50,7 @@ namespace hex
     {
         if (str_size < hex::sizeEncoded(std::span<const uint8_t>(data, data_size)))
         {
-            throw std::logic_error("hex::encode: not enough allocated length");
+            throw std::length_error("hex::encode: not enough allocated length");
         }
         for (uint64_t i = 0; i < data_size; i++)
         {
@@ -72,7 +72,7 @@ namespace hex
         }
         if (data_size < hex::sizeDecoded(std::string_view(str, str_size)))
         {
-            throw std::logic_error("hex::decode: not enough allocated length");
+            throw std::length_error("hex::decode: not enough allocated length");
         }
         if (!hex::isValid(str, str_size))
         {