ls-standard-library/include/ls-std/encoding/Base64.hpp

/*
 * Author:          Patrick-Christopher Mattulat
 * Co-Author:       Claude Sonnet 4.6 (LLM)
 * Company:         Lynar Studios
 * E-Mail:          webmaster@lynarstudios.com
 * Created:         2022-01-03
 * Changed:         2026-06-23
 *
 * */

#ifndef LS_STD_BASE64_HPP
#define LS_STD_BASE64_HPP

#include <bitset>
#include <cstdint>
#include <ls-std/core/interface/IEncoding.hpp>
#include <ls-std/os/dynamic-goal.hpp>
#include <string_view>
#include <unordered_map>
#include <vector>

/*
 * @doc: class(name: 'Base64', package: 'encoding')
 * @doc: encoding.Base64.description('This class can encode and decode the Base64 format.')
 * */

namespace ls::standard::encoding
{
  class LS_STD_DYNAMIC_GOAL Base64 : public ls::standard::core::interface_type::IEncoding
  {
    public:

      Base64();
      ~Base64() noexcept override;

      // implementation

      [[nodiscard]] ::std::string encode(const ::std::string &_sequence) override;
      [[nodiscard]] ::std::string decode(const ::std::string &_sequence) override;

    private:

      [[nodiscard]] static ::std::string _applyEndingRule(::std::string _encodedString, size_t _sequenceSize);
      [[nodiscard]] static ::std::string _decodeByteQuadruple(::std::string_view _quadruple);
      [[nodiscard]] static ::std::string _encodeByteTriple(::std::string_view _byteTriple);
      [[nodiscard]] static uint32_t _extractBitSequence(uint32_t _bitMask, uint32_t _bitStorage);
      [[nodiscard]] static uint32_t _generateBitMask(uint32_t _maskValue, uint8_t _shiftValue);
      [[nodiscard]] static ::std::unordered_map<char, uint8_t> _getDecodingMap();
      [[nodiscard]] static ::std::unordered_map<uint8_t, char> _getEncodingMap();
      [[nodiscard]] static ::std::string_view _getNextByteQuadruple(::std::string_view _sequence, size_t _index);
      [[nodiscard]] static ::std::string_view _getNextByteTriple(::std::string_view _sequence, size_t _index);
      static void _mergeBitSequence(uint32_t &_bitStorage, const uint32_t &_bitMask);
      [[nodiscard]] static uint32_t _toDecodingBitStorage(::std::string_view _quadruple);
      [[nodiscard]] static uint32_t _toEncodingBitStorage(::std::string_view _triple);
  };
}

#endif