serializable.hxx

Go to the documentation of this file.

/*
 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
 *
 * This file is part of StormByte.
 *
 * StormByte original source is dual-licensed:
 *
 * 1. GNU Lesser General Public License v3.0 (or later)
 *    You may redistribute and/or modify this file under the terms of the
 *    GNU Lesser General Public License as published by the Free Software
 *    Foundation, either version 3 of the License, or (at your option)
 *    any later version.
 *
 * 2. Commercial license
 *    Alternatively, this file may be used under the terms of a commercial
 *    license agreement with the copyright holder
 *    (David C. Manuelda <StormByte@gmail.com>).
 *
 * Both licenses apply only to original StormByte source in this repository.
 * They do not cover other StormByte modules or any third-party material
 * shipped with this repository (including everything under thirdparty/),
 * which remains under its own license.
 *
 * Neither license grants any patent rights. Any patent licenses required
 * to use this software or third-party components must be obtained separately
 * from the patent holders.
 *
 * StormByte is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3 along with StormByte. If not, see
 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
 *
 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
 */
 
#pragma once
 
#include <StormByte/binary_data.hxx>
#include <StormByte/byte_size.hxx>
#include <StormByte/safe/cstring.hxx>
#include <StormByte/safe/string.hxx>
#include <StormByte/exception.hxx>
#include <StormByte/expected.hxx>
#include <StormByte/helpers.hxx>
#include <StormByte/type_traits.hxx>
#include <StormByte/visibility.h>
#include <StormByte/safe/wcstring.hxx>
#include <StormByte/safe/wstring.hxx>
 
#include <array>
#include <bit>
#include <cstdint>
#include <cstring>
#include <optional>
#include <span>
#include <string>
#include <tuple>
#include <utility>
 
namespace StormByte {
    class DeserializeError;
 
    namespace Detail {
        template<typename T>
        constexpr bool codec_always_false_v = false;
 
        template<typename T>
        struct Codec {
            static ByteSize Size(const T& data) noexcept {
                static_assert(codec_always_false_v<T>,
                    "Specialize StormByte::Detail::Codec<T> instead of Serializable<T>");
                (void)data;
                return ByteSize{0};
            }
 
            static BinaryData Write(const T& data) noexcept {
                static_assert(codec_always_false_v<T>,
                    "Specialize StormByte::Detail::Codec<T> instead of Serializable<T>");
                (void)data;
                return {};
            }
 
            static Expected<T, DeserializeError> Read(std::span<const std::byte> data) noexcept {
                static_assert(codec_always_false_v<T>,
                    "Specialize StormByte::Detail::Codec<T> instead of Serializable<T>");
                (void)data;
                return Unexpected<DeserializeError>("Codec<T> is not specialized");
            }
        };
 
        template<>
        struct Codec<std::string> {
            static STORMBYTE_PUBLIC ByteSize Size(const std::string& data) noexcept;
 
            static STORMBYTE_PUBLIC BinaryData Write(const std::string& data) noexcept;
 
            static STORMBYTE_PUBLIC Expected<std::string, DeserializeError> Read(std::span<const std::byte> data) noexcept;
        };
 
        template<>
        struct Codec<std::wstring> {
            static STORMBYTE_PUBLIC ByteSize Size(const std::wstring& data) noexcept;
 
            static STORMBYTE_PUBLIC BinaryData Write(const std::wstring& data) noexcept;
 
            static STORMBYTE_PUBLIC Expected<std::wstring, DeserializeError> Read(std::span<const std::byte> data) noexcept;
        };
 
        template<>
        struct Codec<std::u16string> {
            static STORMBYTE_PUBLIC ByteSize Size(const std::u16string& data) noexcept;
 
            static STORMBYTE_PUBLIC BinaryData Write(const std::u16string& data) noexcept;
 
            static STORMBYTE_PUBLIC Expected<std::u16string, DeserializeError> Read(std::span<const std::byte> data) noexcept;
        };
 
        template<>
        struct Codec<std::u32string> {
            static STORMBYTE_PUBLIC ByteSize Size(const std::u32string& data) noexcept;
 
            static STORMBYTE_PUBLIC BinaryData Write(const std::u32string& data) noexcept;
 
            static STORMBYTE_PUBLIC Expected<std::u32string, DeserializeError> Read(std::span<const std::byte> data) noexcept;
        };
 
        template<>
        struct Codec<Safe::CString> {
            static STORMBYTE_PUBLIC ByteSize Size(const Safe::CString& data) noexcept;
 
            static STORMBYTE_PUBLIC BinaryData Write(const Safe::CString& data) noexcept;
 
            static STORMBYTE_PUBLIC Expected<Safe::CString, DeserializeError> Read(std::span<const std::byte> data) noexcept;
        };
 
        template<>
        struct Codec<Safe::WCString> {
            static STORMBYTE_PUBLIC ByteSize Size(const Safe::WCString& data) noexcept;
 
            static STORMBYTE_PUBLIC BinaryData Write(const Safe::WCString& data) noexcept;
 
            static STORMBYTE_PUBLIC Expected<Safe::WCString, DeserializeError> Read(std::span<const std::byte> data) noexcept;
        };
 
        template<>
        struct Codec<Safe::String> {
            static STORMBYTE_PUBLIC ByteSize Size(const Safe::String& data) noexcept;
            static STORMBYTE_PUBLIC BinaryData Write(const Safe::String& data) noexcept;
            static STORMBYTE_PUBLIC Expected<Safe::String, DeserializeError> Read(std::span<const std::byte> data) noexcept;
        };
 
        template<>
        struct Codec<Safe::WString> {
            static STORMBYTE_PUBLIC ByteSize Size(const Safe::WString& data) noexcept;
            static STORMBYTE_PUBLIC BinaryData Write(const Safe::WString& data) noexcept;
            static STORMBYTE_PUBLIC Expected<Safe::WString, DeserializeError> Read(std::span<const std::byte> data) noexcept;
        };
    }
 
    template<typename T>
    class Serializable {
        using DecayedT = std::remove_cvref_t<T>;    
 
        public:
            Serializable(const DecayedT& data) noexcept : m_data(data) {}
 
            Serializable(const Serializable& other) noexcept = delete;
 
            Serializable(Serializable&& other) noexcept = delete;
 
            ~Serializable() noexcept = default;
 
            Serializable& operator=(const Serializable& other) noexcept = delete;
 
            Serializable& operator=(Serializable&& other) noexcept = delete;
 
            BinaryData Serialize() const noexcept;
 
            static Expected<T, DeserializeError> Deserialize(std::span<const std::byte> data) noexcept;
 
            static Expected<T, DeserializeError> Deserialize(const BinaryData& data) noexcept;
 
            static ByteSize Size(const DecayedT& data) noexcept;
 
        private:
            const DecayedT& m_data; 
 
            template<typename U = T>
            BinaryData SerializeTrivial() const noexcept
            requires Type::TriviallyCopyable<U>;
 
            template<typename U = T>
            BinaryData SerializeContainer() const noexcept
            requires Type::Container<U>;
 
            template<typename U = T>
            BinaryData SerializePair() const noexcept
            requires Type::Pair<U>;
 
            template<typename U = T>
            BinaryData SerializeOptional() const noexcept
            requires Type::Optional<U>;
 
            template<typename U = T>
            static ByteSize SizeContainer(const DecayedT& data) noexcept
            requires Type::Container<U>;
 
            template<typename U = T>
            static ByteSize SizePair(const DecayedT& data) noexcept
            requires Type::Pair<U>;
 
            template<typename U = T>
            static ByteSize SizeOptional(const DecayedT& data) noexcept
            requires Type::Optional<U>;
 
            template<typename U = T>
            static Expected<T, DeserializeError> DeserializeTrivial(std::span<const std::byte> data) noexcept
            requires Type::TriviallyCopyable<U>;
 
            template<typename U = T>
            static Expected<T, DeserializeError> DeserializeContainer(std::span<const std::byte> data) noexcept
            requires Type::Container<U>;
 
            template<typename U = T>
            static Expected<T, DeserializeError> DeserializePair(std::span<const std::byte> data) noexcept
            requires Type::Pair<U>;
 
            template<typename U = T>
            static Expected<T, DeserializeError> DeserializeOptional(std::span<const std::byte> data) noexcept
            requires Type::Optional<U>;
    };
 
    // Explicit-instantiation declarations: suppress implicit instantiation
    // of Serializable<T> for these T in every consumer TU. Definitions are
    // in serializable.cxx. STORMBYTE_PUBLIC here is the export/import of
    // those instantiations; the class template itself has no visibility
    // so other modules can instantiate Serializable<TheirType> in their DLL.
    //
    // This block MUST come before `#include <StormByte/serializable.txx>`:
    // those bodies name Serializable<bool> and Serializable<std::uint64_t>
    // as non-dependent types. If the .txx is parsed first, those two are
    // instantiated in this header before the extern declarations.
    extern template class STORMBYTE_PUBLIC Serializable<bool>;
    extern template class STORMBYTE_PUBLIC Serializable<char>;
    extern template class STORMBYTE_PUBLIC Serializable<signed char>;
    extern template class STORMBYTE_PUBLIC Serializable<unsigned char>;
    extern template class STORMBYTE_PUBLIC Serializable<wchar_t>;
    extern template class STORMBYTE_PUBLIC Serializable<char8_t>;
    extern template class STORMBYTE_PUBLIC Serializable<char16_t>;
    extern template class STORMBYTE_PUBLIC Serializable<char32_t>;
    extern template class STORMBYTE_PUBLIC Serializable<short>;
    extern template class STORMBYTE_PUBLIC Serializable<unsigned short>;
    extern template class STORMBYTE_PUBLIC Serializable<int>;
    extern template class STORMBYTE_PUBLIC Serializable<unsigned int>;
    extern template class STORMBYTE_PUBLIC Serializable<long>;
    extern template class STORMBYTE_PUBLIC Serializable<unsigned long>;
    extern template class STORMBYTE_PUBLIC Serializable<long long>;
    extern template class STORMBYTE_PUBLIC Serializable<unsigned long long>;
    extern template class STORMBYTE_PUBLIC Serializable<float>;
    extern template class STORMBYTE_PUBLIC Serializable<double>;
    extern template class STORMBYTE_PUBLIC Serializable<long double>;
    extern template class STORMBYTE_PUBLIC Serializable<std::string>;
    extern template class STORMBYTE_PUBLIC Serializable<std::wstring>;
    extern template class STORMBYTE_PUBLIC Serializable<std::u16string>;
    extern template class STORMBYTE_PUBLIC Serializable<std::u32string>;
    extern template class STORMBYTE_PUBLIC Serializable<Safe::CString>;
    extern template class STORMBYTE_PUBLIC Serializable<Safe::WCString>;
    extern template class STORMBYTE_PUBLIC Serializable<Safe::String>;
    extern template class STORMBYTE_PUBLIC Serializable<Safe::WString>;
    extern template class STORMBYTE_PUBLIC Serializable<BinaryData>;
}
 
#include <StormByte/serializable.txx>