feat(CMake): BASEN_SHARED_LIBS

1.1.0

.gitignore

@@ -39,11 +39,13 @@ WORKSPACE.bazel
 BUILD.bazel
 
 # Dirs
+build
 bin
 obj
 lib
 doc
 cov
+usr
 
 # IDE
 .vscode

AUTHORS

@@ -1,5 +1,5 @@
 libbasen project authors:
 
 commits | username
-     70 | vSEK1RO
+     90 | vSEK1RO
 

CMakeLists.txt

@@ -0,0 +1,33 @@
+cmake_minimum_required(VERSION 3.21)
+set(CMAKE_CXX_STANDARD 20)
+project(libbasen
+    VERSION 1.1.1
+    DESCRIPTION "c++20 encoding/decoding from arbitrary base"
+    LANGUAGES CXX
+)
+
+set(CXX_FLAGS "-Wall -Wextra -Werror -Wno-unused-result -O3")
+
+if(DEFINED BASEN_SHARED_LIBS)
+    set(BUILD_SHARED_LIBS ${BASEN_SHARED_LIBS})
+endif()
+
+set(OBJS
+    base58
+    base64
+    baseN
+    hex
+    Exception
+    hash/sha256
+)
+set(SRCS)
+foreach(OBJ ${OBJS})
+    list(APPEND SRCS "src/${OBJ}.cpp")
+endforeach()
+
+add_library(basen ${SRCS})
+add_library(basen::basen ALIAS basen)
+target_include_directories(basen PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)

Makefile

@@ -8,6 +8,9 @@ USRDIR ?= /usr
 		tools library tests docs cov clean
 
 LIB = basen
+
+TOOLS = ${LIB}
+
 OBJS =\
 	hex\
 	baseN\
@@ -16,8 +19,6 @@ OBJS =\
 	hash/sha256\
 	Exception
 
-TOOLS = ${LIB}
-
 TESTS =\
 	test-hex\
 	test-baseN\
@@ -30,7 +31,7 @@ ifeq (${origin CC}, default)
 CC = g++
 endif
 
-CFLAGS = -std=c++23 -Wall -Wextra -Werror -Wno-unused-result -fPIC
+CFLAGS = -std=c++20 -Wall -Wextra -Werror -Wno-unused-result -fPIC
 
 ifneq (${DEBUG}, false)
 CFLAGS += -fsanitize=address,undefined -g -O0
@@ -58,6 +59,7 @@ USRINC = ${USRDIR}/include
 DIRS =\
 	${BINDIR}\
 	${BINDIR}/hash\
+	${BINDIR}/tools\
 	${OBJDIR}\
 	${OBJDIR}/hash\
 	${LIBDIR}\
@@ -119,19 +121,19 @@ ${USRLIB}/lib${LIB}${-g}%: ${LIBDIR}/lib${LIB}${-g}%
 endif
 ifneq (${TOOLS},)
 
-tools: library ${DIRS} ${patsubst %, ${BINDIR}/%${-g}, ${TOOLS}}
+tools: library ${DIRS} ${patsubst %, ${BINDIR}/tools/%${-g}, ${TOOLS}}
 
-${BINDIR}/%${-g}: ${SRCDIR}/%.cpp ${patsubst %, ${OBJDIR}/%${-g}.o, ${OBJS}}
+${BINDIR}/tools/%${-g}: ${SRCDIR}/tools/%.cpp ${patsubst %, ${OBJDIR}/%${-g}.o, ${OBJS}}
 	${CC} -o $@ $< -I${INCDIR} -L${LIBDIR} ${-l} ${-lLIB} ${CFLAGS}
 
-${USRBIN}/%${-g}: ${BINDIR}/%${-g}
+${USRBIN}/%${-g}: ${BINDIR}/tools/%${-g}
 	install -Dm755 $< $@
 
 endif
 ifneq (${TESTS},)
 
 tests: library ${DIRS} ${patsubst %, ${BINDIR}/%${-g}, ${TESTS}}
-	${patsubst %, ./${BINDIR}/%${-g};, ${TESTS}}
+	echo ${patsubst %, && ./${BINDIR}/%${-g}, ${TESTS}}
 
 ${BINDIR}/%${-g}: ${TESTDIR}/%.cpp ${patsubst %, ${OBJDIR}/%${-g}.o, ${OBJS}}
 	${CC} -o $@ $< -I${INCDIR} -L${LIBDIR} ${-l} ${-lLIB} -lgtest ${CFLAGS}

README.md

@@ -1,6 +1,6 @@
 # libbasen
 
-c++ encoding/decoding from arbitrary base
+c++20 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">
@@ -12,17 +12,24 @@ c++ encoding/decoding from arbitrary base
 ## Contents
 
 - [Installation](#installation)
+    - [Package](#package)
+    - [Make](#make)
+    - [CMake](#cmake)
 - [Documentation](#documentation)
 - [Usage](#usage)
 - [Contributing](#contributing)
 
 ## Installation
 
-Automatically from specified repositories:
+### Package
 
 [![Packaging status](https://repology.org/badge/vertical-allrepos/libbasen.svg)](https://repology.org/project/libbasen/versions)
 
-Manually using make:
+### Make
+
+For cli tool you should have [argparse](https://github.com/p-ranav/argparse) as make dependency.
+
+Install:
 ```
 make -j $(nproc)
 sudo make i USRDIR=(Your installation dir)
@@ -32,6 +39,23 @@ Uninstall:
 sudo make uni USRDIR=(Your installation dir)
 ```
 
+### CMake
+
+For using as dependency only (without cli tool, test, coverage, docs)
+
+```
+set(BASEN_SHARED_LIBS ON)
+include(FetchContent)
+FetchContent_Declare(
+    basen
+    GIT_REPOSITORY https://github.com/vSEK1RO/libbasen.git
+    GIT_TAG        latest
+)
+FetchContent_MakeAvailable(basen)
+
+target_link_libraries(MyProject PRIVATE basen::basen)
+```
+
 ## Documentation
 
 Available [here](https://vsek1ro.github.io/libbasen)

include/basen/base58.hpp

@@ -13,39 +13,72 @@ namespace base58
     extern const char digits[59];
     extern const uint8_t map[256];
 
+    /**
+     * @return checks what contains only alphabet chars
+     * @warning doesn't validate checksum, use decodeCheck instead
+     */
     bool isValid(const char *str, size_t str_size) noexcept;
+    /**
+     * @param str string or string_view which you want to decode
+     * @return checks what contains only alphabet chars
+     * @warning doesn't validate checksum, use decodeCheck instead
+     */
     bool isValid(std::string_view str) noexcept;
 
     /**
-     * @throw basen::Exception(OVERFLOW) if there is an overflow
+     * @param data vector or span of data which you want to encode
+     * @return estimated size after encoding (for non-powers of two it is obviously larger)
+     * @throw basen::Exception(OVERFLOW) from baseN::sizeEncoded
      */
     size_t sizeEncoded(std::span<const uint8_t> data);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return estimated size after decoding (for non-powers of two it is obviously larger)
+     */
     size_t sizeDecoded(std::string_view str) noexcept;
 
     /**
+     * @param data [in] pointer to data which you want encode
+     * @param str [out] pointer to string for encoded data output
      * @return number of leading chars, which should be trimmed
+     * @throw basen::Exception(OVERFLOW) from base58::sizeEncoded
      * @warning contain leading zeros, returns count of them
      */
     size_t encode(const uint8_t *data, size_t data_size, char *str, size_t str_size);
+    /**
+     * @param data vector or span of data which you want to encode
+     * @return encoded string
+     * @throw basen::Exception(OVERFLOW) from base58::sizeEncoded
+     */
     std::string encode(std::span<const uint8_t> data);
 
     /**
+     * @param str [in] pointer to string which you want decode
+     * @param data [out] pointer to data for encoded string output
      * @return number of leading chars, which should be trimmed
+     * @throw basen::Exception(OUT_OF_ALPH) from baseN::decode
      * @warning contain leading zeros, returns count of them
      */
     size_t decode(const char *str, size_t str_size, uint8_t *data, size_t data_size);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return decoded data
+     * @throw basen::Exception(OUT_OF_ALPH) from baseN::decode
+     */
     std::vector<uint8_t> decode(std::string_view str);
 
     /**
      * @param data vector or span of data which you want to encode
      * @return encoded string + 4 first bytes of double sha256
+     * @throw basen::Exception(OVERFLOW) from base58::encode
      */
     std::string encodeCheck(std::span<const uint8_t> data);
     /**
-     * @param str string or string_view which you want to decode
+     * @param str encoded string or string_view + 4 first bytes of double sha256
      * @return decoded data without 4 first bytes of double sha256
+     * @throw basen::Exception(OUT_OF_ALPH) from base58::decode
      * @throw basen::Exception(PADDING) if str size < 4
-     * @throw basen::Exception(CHECKSUM) checksum incorrect
+     * @throw basen::Exception(CHECKSUM) if checksum incorrect
      */
     std::vector<uint8_t> decodeCheck(std::string_view str);
 }

include/basen/base64.hpp

@@ -10,28 +10,57 @@ namespace base64
     extern const char digits[65];
     extern const uint8_t map[256];
 
+    /**
+     * @return checks what contains only alphabet chars and ends with no more than two '=' chars
+     */
     bool isValid(const char *str, size_t str_size) noexcept;
+    /**
+     * @param str string or string_view which you want to decode
+     * @return checks what contains only alphabet chars and ends with no more than two '=' chars
+     */
     bool isValid(std::string_view str) noexcept;
 
     /**
+     * @param data vector or span of data which you want to encode
+     * @return exact size after encoding
      * @throw basen::Exception(OVERFLOW) if there is an overflow
      */
     size_t sizeEncoded(std::span<const uint8_t> data);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return exact size after decoding
+     */
     size_t sizeDecoded(std::string_view str) noexcept;
 
     /**
+     * @param data [in] pointer to data which you want encode
+     * @param str [out] pointer to string for encoded data output
+     * @throw basen::Exception(OVERFLOW) from base64::sizeEncoded
      * @throw basen::Exception(LENGTH) if not enough allocated length
-     * @warning contain leading zeros, returns count of them
      */
     void encode(const uint8_t *data, size_t data_size, char *str, size_t str_size);
+    /**
+     * @param data vector or span of data which you want to encode
+     * @return encoded string
+     * @throw basen::Exception(OVERFLOW) from base64::sizeEncoded
+     * @throw basen::Exception(LENGTH) if not enough allocated length
+     */
     std::string encode(std::span<const uint8_t> data);
 
     /**
+     * @param str [in] pointer to string which you want decode
+     * @param data [out] pointer to data for encoded string output
      * @throw basen::Exception(LENGTH) if not enough allocated length
      * @throw basen::Exception(OUT_OF_ALPH) if out of digits map
      * @throw basen::Exception(PADDING) if incorrect padding
-     * @warning contain leading zeros, returns count of them
      */
     void decode(const char *str, size_t str_size, uint8_t *data, size_t data_size);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return decoded data
+     * @throw basen::Exception(LENGTH) if not enough allocated length
+     * @throw basen::Exception(OUT_OF_ALPH) if out of digits map
+     * @throw basen::Exception(PADDING) if incorrect padding
+     */
     std::vector<uint8_t> decode(std::string_view str);
 }

include/basen/baseN.hpp

@@ -8,38 +8,36 @@
 namespace baseN
 {
     /**
-     * @param digits char[base] array of digits
+     * @param digits [in] alphabet of encoding
-     * @param digits_size size of digits array. Equals to base
      * @param map [out] uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 if there is no symbol
+     * @return map of alphabet of encoding
      * @throw basen::Exception(ALPH_COLLISION) if alphabet contain same chars
      */
     void digitsMap(const char *digits, uint8_t digits_size, uint8_t *map);
     /**
-     * @param str [in] pointer to string
+     * @param map map of alphabet of encoding, which is returned by baseN::digitsMap
-     * @param str_size
+     * @return checks what contains only alphabet chars
-     * @param map uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 if there is no symbol
-     * @return that string doesn't contain unnecessary symbols
      */
     bool isValid(const char *str, size_t str_size, const uint8_t *map) noexcept;
     /**
      * @param str string or string_view which you want to decode
-     * @param map uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 if there is no symbol
+     * @param map map of alphabet of encoding, which is returned by baseN::digitsMap
-     * @return that string doesn't contain unnecessary symbols
+     * @return checks what contains only alphabet chars
      */
     bool isValid(std::string_view str, const uint8_t *map) noexcept;
 
     /**
      * @param data vector or span of data which you want to encode
-     * @param base from 1 to 255
+     * @param base radix of encoding from [2 to 254]
-     * @return estimated size after encoding
+     * @return estimated size after encoding (obviously larger)
      * @throw basen::Exception(BASE) if base < 2 || base > 254
      */
     size_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 base radix of encoding from [2 to 254]
-     * @param digits char[base] array of digits
+     * @param digits alphabet of encoding
-     * @return estimated size after decoding
+     * @return estimated size after decoding (obviously larger)
      * @throw basen::Exception(BASE) if base < 2 || base > 254
      * @throw basen::Exception(OVERFLOW) if if there is an overflow
      */
@@ -47,19 +45,9 @@ namespace baseN
 
     /**
      * @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 radix of encoding from [2 to 254]
-     * @param base from 1 to 255
+     * @param digits alphabet of encoding
-     * @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
      * @throw basen::Exception(BASE) if base < 2 || base > 254
      * @warning contain leading zeros, returns count of them
@@ -67,32 +55,19 @@ namespace baseN
     size_t encode(const uint8_t *data, size_t data_size, char *str, size_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 base radix of encoding from [2 to 254]
-     * @param digits char[base] array of digits
+     * @param digits alphabet of encoding
-     * @code{cpp}
-     * std::vector<uint8_t> data;
-     * auto str = baseN::encode(data, 58, base58::digits);
-     * @endcode
      * @return encoded string
+     * @throw basen::Exception(BASE) if base < 2 || base > 254
      */
     std::string encode(std::span<const uint8_t> data, uint8_t base, const char *digits);
 
     /**
      * @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 radix of encoding from [2 to 254]
-     * @param base from 1 to 255
+     * @param digits alphabet of encoding
-     * @param digits char[base] array of digits
+     * @param map map of alphabet of encoding, which is returned by baseN::digitsMap
-     * @param map uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 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
      * @throw basen::Exception(BASE) if base < 2 || base > 254
      * @throw basen::Exception(OUT_OF_ALPH) if out of alphabet
@@ -101,14 +76,12 @@ namespace baseN
     size_t decode(const char *str, size_t str_size, uint8_t *data, size_t data_size, uint8_t base, const char *digits, const uint8_t *map);
     /**
      * @param str string or string_view which you want to decode
-     * @param base from 1 to 255
+     * @param base radix of encoding from [2 to 254]
-     * @param digits char[base] array of digits
+     * @param digits alphabet of encoding
-     * @param map uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 if there is no symbol
+     * @param map map of alphabet of encoding, which is returned by baseN::digitsMap
-     * @code{cpp}
-     * std::string str;
-     * auto data = baseN::decode(str, 58, base58::digits, base58::map);
-     * @endcode
      * @return decoded data
+     * @throw basen::Exception(BASE) if base < 2 || base > 254
+     * @throw basen::Exception(OUT_OF_ALPH) if out of alphabet
      */
     std::vector<uint8_t> decode(std::string_view str, uint8_t base, const char *digits, const uint8_t *map);
 }

include/basen/hex.hpp

@@ -7,31 +7,62 @@
 
 namespace hex
 {
+    /**
+     * @brief lower case chars
+     */
     extern const char digits[17];
     extern const uint8_t map[256];
 
+    /**
+     * @return checks what contains only alphabet chars
+     */
     bool isValid(const char *str, size_t str_size) noexcept;
+    /**
+     * @param str string or string_view which you want to decode
+     * @return checks what contains only alphabet chars
+     */
     bool isValid(std::string_view str) noexcept;
 
     /**
+     * @param data vector or span of data which you want to encode
+     * @return exact size after encoding
      * @throw basen::Exception(OVERFLOW) if there is an overflow
      */
     size_t sizeEncoded(std::span<const uint8_t> data);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return exact size after decoding
+     */
     size_t sizeDecoded(std::string_view str) noexcept;
 
     /**
+     * @param data [in] pointer to data which you want encode
+     * @param str [out] pointer to string for encoded data output
+     * @throw basen::Exception(OVERFLOW) from hex::sizeEncoded
      * @throw basen::Exception(LENGTH) if not enough allocated length
-     * @warning contain leading zeros, returns count of them
      */
     void encode(const uint8_t *data, size_t data_size, char *str, size_t str_size);
+    /**
+     * @param data vector or span of data which you want to encode
+     * @return encoded string
+     * @throw basen::Exception(OVERFLOW) from hex::sizeEncoded
+     * @throw basen::Exception(LENGTH) if not enough allocated length
+     */
     std::string encode(std::span<const uint8_t> data);
 
     /**
+     * @param str [in] pointer to string which you want decode
+     * @param data [out] pointer to data for encoded string output
      * @throw basen::Exception(LENGTH) if not enough allocated length
      * @throw basen::Exception(OUT_OF_ALPH) if out of digits map
      * @throw basen::Exception(PADDING) if str_size %2 != 0 (isn't hex)
-     * @warning contain leading zeros, returns count of them
      */
     void decode(const char *str, size_t str_size, uint8_t *data, size_t data_size);
+    /**
+     * @param str string or string_view which you want to decode
+     * @throw basen::Exception(LENGTH) if not enough allocated length
+     * @throw basen::Exception(OUT_OF_ALPH) if out of digits map
+     * @throw basen::Exception(PADDING) if str_size %2 != 0 (isn't hex)
+     */
     std::vector<uint8_t> decode(std::string_view str);
 }