From e28d103da0b385e5ad119914699091e5a0689785 Mon Sep 17 00:00:00 2001
From: SEK1RO <vlad@sek1.ro>
Date: Sun, 22 Sep 2024 22:00:13 +0300
Subject: [PATCH] feat(docs): base58.hpp

---
 include/basen/base58.hpp | 27 +++++++++++++++++++++++++--
 include/basen/base64.hpp |  2 ++
 include/basen/hex.hpp    |  4 +++-
 src/base58.cpp           |  8 ++++----
 4 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/include/basen/base58.hpp b/include/basen/base58.hpp
index ee1e693..aa9685d 100644
--- a/include/basen/base58.hpp
+++ b/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);
 }
\ No newline at end of file
diff --git a/include/basen/base64.hpp b/include/basen/base64.hpp
index 41b380f..cd116b0 100644
--- a/include/basen/base64.hpp
+++ b/include/basen/base64.hpp
@@ -21,6 +21,7 @@ namespace base64
 
     /**
      * @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;
@@ -29,6 +30,7 @@ namespace base64
      * @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;
diff --git a/include/basen/hex.hpp b/include/basen/hex.hpp
index 5280dce..afd2a55 100644
--- a/include/basen/hex.hpp
+++ b/include/basen/hex.hpp
@@ -21,14 +21,16 @@ namespace hex
 
     /**
      * @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;
diff --git a/src/base58.cpp b/src/base58.cpp
index 6808463..509c8ae 100644
--- a/src/base58.cpp
+++ b/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
     {