feat(docs): baseN.hpp

feat(.github): docs.yml
fix(doxygen-awesome): moved to deps dir
2024-09-22 21:00:54 +03:00 · 2024-09-22 20:24:45 +03:00 · 2024-09-22 20:03:22 +03:00 · 2024-09-22 19:51:15 +03:00 · 2024-09-22 17:11:15 +03:00 · 2024-09-21 22:41:34 +03:00
11 changed files with 3203 additions and 6 deletions
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@ -0,0 +1,39 @@
+name: Deploy documentation
+
+on:
+  push:
+    branches: ["main"]
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Install Doxygen
+        run: sudo apt install doxygen
+      - name: Generate docs
+        run: doxygen
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'doc/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
--- a/.gitignore
+++ b/.gitignore
@ -42,6 +42,7 @@ BUILD.bazel
 bin
 obj
 lib
+doc

 # IDE
 .vscode
--- a/.gitmodules
+++ b/.gitmodules
@ -0,0 +1,6 @@
+[submodule "distrib/arch"]
+	path = distrib/arch
+	url = https://aur.archlinux.org/libbasen.git
+[submodule "deps/doxygen-awesome-css"]
+	path = deps/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git
--- a/4
+++ b/4
@ -1,5 +1,5 @@
-libbasen authors:
+libbasen project authors:

 commits | username
-     45 | vSEK1RO
+     46 | vSEK1RO

--- a/2927
+++ b/2927
--- a/5
+++ b/5
@ -5,7 +5,7 @@ DEBUG ?= false
 USRDIR ?= /usr

 .PHONY: build i install uni uninstall\
-		tools library tests clean
+		tools library tests docs clean

 LIB = basen
 OBJS =\
@ -77,6 +77,9 @@ uninstall:
 	rm -f ${patsubst %, ${USRLIB}/lib${LIB}${-g}%, .so .a}
 	rm -f ${patsubst %, ${USRBIN}/%${-g}, ${TOOLS}}

+docs:
+	doxygen Doxyfile
+
 clean:
 	rm -rf ${OBJDIR}/* ${LIBDIR}/* ${BINDIR}/*

--- a/README.md
+++ b/README.md
@ -1,3 +1,54 @@
-# libbase
+# libbasen

-encoding/decoding from arbitrary base
+c++ encoding/decoding from arbitrary base
+
+<a href="https://repology.org/project/libbasen/versions">
+    <img src="https://repology.org/badge/tiny-repos/libbasen.svg" alt="Packaging status">
+</a>
+<a href="https://repology.org/project/libbasen/versions">
+    <img src="https://repology.org/badge/latest-versions/libbasen.svg" alt="latest packaged version(s)">
+</a>
+
+## Contents
+
+- [Installation](#installation)
+- [Contributing](#contributing)
+
+## Installation
+
+Automatically from specified repositories:
+
+[![Packaging status](https://repology.org/badge/vertical-allrepos/libbasen.svg)](https://repology.org/project/libbasen/versions)
+
+Manually using make:
+```
+make -j $(nproc)
+sudo make i USRDIR=(Your installation dir)
+```
+Uninstall:
+```
+sudo make uni USRDIR=(Your installation dir)
+```
+For build with with debug flags:
+```
+make -j $(nproc) DEBUG=
+```
+For build tests (needed gtest package as dependency):
+```
+make tests -j $(nproc) DEBUG=
+```
+And also flag for dynamic linking (if possible):
+```
+make tools -j $(nproc) SHARED=
+```
+
+## 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.
+
+Now we would like to implement the following features:
+- Base32
+- BCH
+- Bech32
+
+[⬆️ Contents](#contents)
--- a/deps/doxygen-awesome-css
+++ b/deps/doxygen-awesome-css
--- a/distrib/arch
+++ b/distrib/arch
--- a/header.html
+++ b/header.html
@ -0,0 +1,88 @@
+<!-- HTML header for doxygen 1.12.0-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=11"/>
+<meta name="generator" content="Doxygen $doxygenversion"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
+<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<!--BEGIN PROJECT_ICON-->
+<link rel="icon" href="$relpath^$projecticon" type="image/x-icon" />
+<!--END PROJECT_ICON-->
+<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
+<!--BEGIN DISABLE_INDEX-->  
+  <!--BEGIN FULL_SIDEBAR-->
+<script type="text/javascript">var page_layout=1;</script>
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+<script type="text/javascript" src="$relpath^jquery.js"></script>
+<script type="text/javascript" src="$relpath^dynsections.js"></script>
+<!--BEGIN COPY_CLIPBOARD-->
+<script type="text/javascript" src="$relpath^clipboard.js"></script>
+<!--END COPY_CLIPBOARD-->
+$treeview
+$search
+$mathjax
+$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">
+      DoxygenAwesomeFragmentCopyButton.init()
+  </script>
+</head>
+<body>
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+
+<!--BEGIN TITLEAREA-->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr id="projectrow">
+  <!--BEGIN PROJECT_LOGO-->
+  <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"$logosize/></td>
+  <!--END PROJECT_LOGO-->
+  <!--BEGIN PROJECT_NAME-->
+  <td id="projectalign">
+   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
+   </div>
+   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
+  </td>
+  <!--END PROJECT_NAME-->
+  <!--BEGIN !PROJECT_NAME-->
+   <!--BEGIN PROJECT_BRIEF-->
+    <td>
+    <div id="projectbrief">$projectbrief</div>
+    </td>
+   <!--END PROJECT_BRIEF-->
+  <!--END !PROJECT_NAME-->
+  <!--BEGIN DISABLE_INDEX-->
+   <!--BEGIN SEARCHENGINE-->
+     <!--BEGIN !FULL_SIDEBAR-->
+    <td>$searchbox</td>
+     <!--END !FULL_SIDEBAR-->
+   <!--END SEARCHENGINE-->
+  <!--END DISABLE_INDEX-->
+ </tr>
+  <!--BEGIN SEARCHENGINE-->
+   <!--BEGIN FULL_SIDEBAR-->
+   <tr><td colspan="2">$searchbox</td></tr>
+   <!--END FULL_SIDEBAR-->
+  <!--END SEARCHENGINE-->
+ </tbody>
+</table>
+</div>
+<!--END TITLEAREA-->
+<!-- end header part -->
--- a/include/basen/baseN.hpp
+++ b/include/basen/baseN.hpp
@ -7,15 +7,95 @@

 namespace baseN
 {
+    /**
+     * @param str [in] pointer to string
+     * @param str_size
+     * @param map int8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. -1 if there is no symbol
+     * @return that string doesn't contain unnecessary symbols
+     */
    bool isValid(const char *str, uint64_t str_size, const int8_t *map) noexcept;
+    /**
+     * @param str string or string_view which you want to decode
+     * @param map int8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. -1 if there is no symbol
+     * @return that string doesn't contain unnecessary symbols
+     */
    bool isValid(std::string_view str, const int8_t *map) noexcept;

+    /**
+     * @param data vector or span of data which you want to encode
+     * @param base from 1 to 255
+     * @return estimated size after encoding
+     */
    uint64_t sizeEncoded(std::span<const uint8_t> data, uint8_t base);
+    /**
+     * @param str string or string_view which you want to decode
+     * @param base from 1 to 255
+     * @param digits char[base] array of digits
+     * @return estimated size after decoding
+     */
    uint64_t sizeDecoded(std::string_view str, uint8_t base, const char *digits) noexcept;

+    /**
+     * @param data [in] pointer to data which you want encode
+     * @param data_size
+     * @param str [out] pointer to string for encoded data output
+     * @param str_size
+     * @param base from 1 to 255
+     * @param digits char[base] array of digits
+     * @code{cpp}
+     * std::vector<uint8_t> data;
+     * std::string str(baseN::sizeEncoded(data, 58), ' ');
+     * 
+     * auto offset = baseN::encode(data.data(), data.size(), str.data(), str.size(), 58, base58::digits);
+     * // deleting leading zeroes
+     * str.erase(str.begin(), str.begin() + offset);
+     * @endcode
+     * @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, uint8_t base, const char *digits);
+    /**
+     * @param data vector or span of data which you want to encode
+     * @param base from 1 to 255
+     * @param digits char[base] array of digits
+     * @code{cpp}
+     * std::vector<uint8_t> data;
+     * auto str = baseN::encode(data, 58, base58::digits);
+     * @endcode
+     * @return encoded string
+     */
    std::string encode(std::span<const uint8_t> data, uint8_t base, const char *digits) noexcept;

+    /**
+     * @param str [in] pointer to string which you want decode
+     * @param str_size
+     * @param data [out] pointer to data for encoded string output
+     * @param data_size
+     * @param base from 1 to 255
+     * @param digits char[base] array of digits
+     * @param map int8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. -1 if there is no symbol
+     * @code{cpp}
+     * std::string str;
+     * std::vector<uint8_t> data(baseN::sizeDecoded(str, 58));
+     * 
+     * auto offset = baseN::decode(str.data(), str.size(), data.data(), data.size(), 58, base58::digits, base58::map);
+     * // deleting leading zeroes
+     * data.erase(data.begin(), data.begin() + offset);
+     * @endcode
+     * @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, uint8_t base, const char *digits, const int8_t *map);
+    /**
+     * @param str string or string_view which you want to decode
+     * @param base from 1 to 255
+     * @param digits char[base] array of digits
+     * @param map int8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. -1 if there is no symbol
+     * @code{cpp}
+     * std::string str;
+     * auto data = baseN::decode(str, 58, base58::digits, base58::map);
+     * @endcode
+     * @return decoded data
+     */
    std::vector<uint8_t> decode(std::string_view str, uint8_t base, const char *digits, const int8_t *map) noexcept;
 }
Author	SHA1	Message	Date
SEK1RO	b61d8396f5	feat(docs): baseN.hpp	2024-09-22 21:00:54 +03:00
SEK1RO	53279581aa	feat(.github): docs.yml	2024-09-22 20:24:45 +03:00
SEK1RO	f4b5dc0ce0	fix(doxygen-awesome): moved to deps dir	2024-09-22 20:03:22 +03:00
SEK1RO	a5374daa6f	feat(Doxyfile, doxygen-awesome)	2024-09-22 19:51:15 +03:00
SEK1RO	baf52bb404	fix(submodule): distrib/arch added to .gitmodules	2024-09-22 17:11:15 +03:00
SEK1RO	f47f367045	fix(README.md): styles	2024-09-21 22:41:34 +03:00
SEK1RO	fd660f3b56	feat(README.md): contents, installation, contribution	2024-09-21 22:30:36 +03:00
SEK1RO	78276e8c88	submodule(distrib): aur	2024-09-21 16:14:13 +03:00