StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
serializable.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This is the base for StormByte Suite libraries.
5 *
6 * StormByte original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte source in this repository.
20 * They do not cover other StormByte modules or any third-party material
21 * shipped with this repository (including everything under thirdparty/),
22 * which remains under its own license.
23 *
24 * Neither license grants any patent rights. Any patent licenses required
25 * to use this software or third-party components must be obtained separately
26 * from the patent holders.
27 *
28 * StormByte is distributed in the hope that it will be useful,
29 * but WITHOUT ANY WARRANTY; without even the implied warranty of
30 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 * GNU Lesser General Public License for more details.
32 *
33 * You should have received a copy of the GNU Lesser General Public License
34 * version 3 along with StormByte. If not, see
35 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
36 *
37 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
38 */
39
40#pragma once
41
45#include <StormByte/helpers.hxx>
52
53#include <array>
54#include <bit>
55#include <cstdint>
56#include <cstring>
57#include <optional>
58#include <span>
59#include <string>
60#include <tuple>
61#include <utility>
62
67namespace StormByte {
68 class DeserializeError;
69
77 namespace Detail {
82 template<typename T>
83 constexpr bool codec_always_false_v = false;
84
107 template<typename T>
108 struct Codec {
114 static ByteSize Size(const T& data) noexcept {
115 static_assert(codec_always_false_v<T>,
116 "Specialize StormByte::Detail::Codec<T> instead of Serializable<T>");
117 (void)data;
118 return ByteSize{0};
119 }
120
126 static Safe::Binary Write(const T& data) noexcept {
127 static_assert(codec_always_false_v<T>,
128 "Specialize StormByte::Detail::Codec<T> instead of Serializable<T>");
129 (void)data;
130 return {};
131 }
132
138 static Expected<T, DeserializeError> Read(std::span<const std::byte> data) noexcept {
139 static_assert(codec_always_false_v<T>,
140 "Specialize StormByte::Detail::Codec<T> instead of Serializable<T>");
141 (void)data;
142 return Unexpected<DeserializeError>("Codec<T> is not specialized");
143 }
144 };
145
151 template<>
152 struct Codec<std::string> {
158 static STORMBYTE_PUBLIC ByteSize Size(const std::string& data) noexcept;
159
165 static STORMBYTE_PUBLIC Safe::Binary Write(const std::string& data) noexcept;
166
173 static Expected<std::string, DeserializeError> Read(std::span<const std::byte> data) noexcept;
174 };
175
182 template<>
183 struct Codec<std::wstring> {
189 static STORMBYTE_PUBLIC ByteSize Size(const std::wstring& data) noexcept;
190
196 static STORMBYTE_PUBLIC Safe::Binary Write(const std::wstring& data) noexcept;
197
204 static Expected<std::wstring, DeserializeError> Read(std::span<const std::byte> data) noexcept;
205 };
206
212 template<>
213 struct Codec<std::u16string> {
219 static STORMBYTE_PUBLIC ByteSize Size(const std::u16string& data) noexcept;
220
226 static STORMBYTE_PUBLIC Safe::Binary Write(const std::u16string& data) noexcept;
227
234 static Expected<std::u16string, DeserializeError> Read(std::span<const std::byte> data) noexcept;
235 };
236
242 template<>
243 struct Codec<std::u32string> {
249 static STORMBYTE_PUBLIC ByteSize Size(const std::u32string& data) noexcept;
250
256 static STORMBYTE_PUBLIC Safe::Binary Write(const std::u32string& data) noexcept;
257
264 static Expected<std::u32string, DeserializeError> Read(std::span<const std::byte> data) noexcept;
265 };
266
275 template<>
276 struct Codec<Safe::String> {
282 static STORMBYTE_PUBLIC ByteSize Size(const Safe::String& data) noexcept;
283
289 static STORMBYTE_PUBLIC Safe::Binary Write(const Safe::String& data) noexcept;
290
296 static STORMBYTE_PUBLIC Expected<Safe::String, DeserializeError> Read(std::span<const std::byte> data) noexcept;
297 };
298
307 template<>
308 struct Codec<Safe::WString> {
314 static STORMBYTE_PUBLIC ByteSize Size(const Safe::WString& data) noexcept;
315
321 static STORMBYTE_PUBLIC Safe::Binary Write(const Safe::WString& data) noexcept;
322
328 static STORMBYTE_PUBLIC Expected<Safe::WString, DeserializeError> Read(std::span<const std::byte> data) noexcept;
329 };
330
338 STORMBYTE_FORCE_INLINE bool NextUtf8(std::string_view utf8, std::size_t& index, char32_t& cp) noexcept {
339 if (index >= utf8.size())
340 return false;
341
342 const auto lead = static_cast<unsigned char>(utf8[index++]);
343 int extra = 0;
344 if (lead < 0x80u) {
345 cp = lead;
346 return true;
347 } else if ((lead & 0xE0u) == 0xC0u) {
348 cp = lead & 0x1Fu;
349 extra = 1;
350 } else if ((lead & 0xF0u) == 0xE0u) {
351 cp = lead & 0x0Fu;
352 extra = 2;
353 } else if ((lead & 0xF8u) == 0xF0u) {
354 cp = lead & 0x07u;
355 extra = 3;
356 } else {
357 cp = 0xFFFDu;
358 return true;
359 }
360
361 for (int n = 0; n < extra; ++n) {
362 if (index >= utf8.size()) {
363 cp = 0xFFFDu;
364 return true;
365 }
366 const auto cont = static_cast<unsigned char>(utf8[index]);
367 if ((cont & 0xC0u) != 0x80u) {
368 cp = 0xFFFDu;
369 return true;
370 }
371 ++index;
372 cp = (cp << 6) | (cont & 0x3Fu);
373 }
374
375 if (cp > 0x10FFFFu || (cp >= 0xD800u && cp <= 0xDFFFu))
376 cp = 0xFFFDu;
377 return true;
378 }
379
381 auto payload = Codec<Safe::String>::Read(data);
382 if (!payload)
383 return Unexpected(payload.error());
384 return std::string(static_cast<std::string_view>(payload.value()));
385 }
386
388 auto payload = Codec<Safe::WString>::Read(data);
389 if (!payload)
390 return Unexpected(payload.error());
391 return std::wstring(static_cast<std::wstring_view>(payload.value()));
392 }
393
395 auto payload = Codec<Safe::String>::Read(data);
396 if (!payload)
397 return Unexpected(payload.error());
398 const std::string_view utf8 = payload.value();
399 std::u16string out;
400 std::size_t index = 0;
401 char32_t cp = 0;
402 while (NextUtf8(utf8, index, cp)) {
403 if (cp <= 0xFFFFu) {
404 out.push_back(static_cast<char16_t>(cp));
405 } else {
406 cp -= 0x10000u;
407 out.push_back(static_cast<char16_t>(0xD800u + (cp >> 10)));
408 out.push_back(static_cast<char16_t>(0xDC00u + (cp & 0x3FFu)));
409 }
410 }
411 return out;
412 }
413
415 auto payload = Codec<Safe::String>::Read(data);
416 if (!payload)
417 return Unexpected(payload.error());
418 const std::string_view utf8 = payload.value();
419 std::u32string out;
420 std::size_t index = 0;
421 char32_t cp = 0;
422 while (NextUtf8(utf8, index, cp))
423 out.push_back(cp);
424 return out;
425 }
426 }
427
450 template<typename T>
452 using DecayedT = std::remove_cvref_t<T>;
453
455 "Safe::SecureBinary is not serializable: the blob would hold the secret in memory that is never wiped");
456
457 public:
462 Serializable(const DecayedT& data) noexcept : m_data(data) {}
463
467 Serializable(const Serializable& other) noexcept = delete;
468
472 Serializable(Serializable&& other) noexcept = delete;
473
477 ~Serializable() noexcept = default;
478
482 Serializable& operator=(const Serializable& other) noexcept = delete;
483
487 Serializable& operator=(Serializable&& other) noexcept = delete;
488
493 Safe::Binary Serialize() const noexcept;
494
500 static Expected<T, DeserializeError> Deserialize(std::span<const std::byte> data) noexcept;
501
507 static Expected<T, DeserializeError> Deserialize(const Safe::Binary& data) noexcept;
508
514 static ByteSize Size(const DecayedT& data) noexcept;
515
516 private:
517 const DecayedT& m_data;
518
531 template<typename U = T>
532 Safe::Binary SerializeTrivial() const noexcept
533 requires Type::TriviallyCopyable<U>;
534
540 template<typename U = T>
541 Safe::Binary SerializeContainer() const noexcept
542 requires Type::Container<U>;
543
549 template<typename U = T>
550 Safe::Binary SerializePair() const noexcept
551 requires Type::Pair<U>;
552
561 template<typename U = T>
562 Safe::Binary SerializeOptional() const noexcept
563 requires Type::Optional<U>;
564
570 template<typename U = T>
571 Safe::Binary SerializeQueue() const noexcept
572 requires Type::Queue<U>;
573
580 template<typename U = T>
581 static ByteSize SizeContainer(const DecayedT& data) noexcept
582 requires Type::Container<U>;
583
590 template<typename U = T>
591 static ByteSize SizePair(const DecayedT& data) noexcept
592 requires Type::Pair<U>;
593
600 template<typename U = T>
601 static ByteSize SizeOptional(const DecayedT& data) noexcept
602 requires Type::Optional<U>;
603
610 template<typename U = T>
611 static ByteSize SizeQueue(const DecayedT& data) noexcept
612 requires Type::Queue<U>;
613
624 template<typename U = T>
625 static Expected<T, DeserializeError> DeserializeTrivial(std::span<const std::byte> data) noexcept
626 requires Type::TriviallyCopyable<U>;
627
634 template<typename U = T>
635 static Expected<T, DeserializeError> DeserializeContainer(std::span<const std::byte> data) noexcept
636 requires Type::Container<U>;
637
644 template<typename U = T>
645 static Expected<T, DeserializeError> DeserializePair(std::span<const std::byte> data) noexcept
646 requires Type::Pair<U>;
647
654 template<typename U = T>
655 static Expected<T, DeserializeError> DeserializeOptional(std::span<const std::byte> data) noexcept
656 requires Type::Optional<U>;
657
664 template<typename U = T>
665 static Expected<T, DeserializeError> DeserializeQueue(std::span<const std::byte> data) noexcept
666 requires Type::Queue<U>;
667 };
668
669 // Explicit-instantiation declarations: suppress implicit instantiation
670 // of Serializable<T> for these T in every consumer TU. Definitions are
671 // in serializable.cxx. STORMBYTE_PUBLIC here is the export/import of
672 // those instantiations; the class template itself has no visibility
673 // so other modules can instantiate Serializable<TheirType> in their DLL.
674 //
675 // This block MUST come before `#include <StormByte/serializable.txx>`:
676 // those bodies name Serializable<bool> and Serializable<std::uint64_t>
677 // as non-dependent types. If the .txx is parsed first, those two are
678 // instantiated in this header before the extern declarations.
680 extern template class STORMBYTE_PUBLIC Serializable<bool>;
681 extern template class STORMBYTE_PUBLIC Serializable<char>;
682 extern template class STORMBYTE_PUBLIC Serializable<signed char>;
683 extern template class STORMBYTE_PUBLIC Serializable<unsigned char>;
684 extern template class STORMBYTE_PUBLIC Serializable<wchar_t>;
685 extern template class STORMBYTE_PUBLIC Serializable<char8_t>;
686 extern template class STORMBYTE_PUBLIC Serializable<char16_t>;
687 extern template class STORMBYTE_PUBLIC Serializable<char32_t>;
688 extern template class STORMBYTE_PUBLIC Serializable<short>;
689 extern template class STORMBYTE_PUBLIC Serializable<unsigned short>;
690 extern template class STORMBYTE_PUBLIC Serializable<int>;
691 extern template class STORMBYTE_PUBLIC Serializable<unsigned int>;
692 extern template class STORMBYTE_PUBLIC Serializable<long>;
693 extern template class STORMBYTE_PUBLIC Serializable<unsigned long>;
694 extern template class STORMBYTE_PUBLIC Serializable<long long>;
695 extern template class STORMBYTE_PUBLIC Serializable<unsigned long long>;
696 extern template class STORMBYTE_PUBLIC Serializable<float>;
697 extern template class STORMBYTE_PUBLIC Serializable<double>;
698 extern template class STORMBYTE_PUBLIC Serializable<long double>;
699 extern template class STORMBYTE_PUBLIC Serializable<Safe::String>;
700 extern template class STORMBYTE_PUBLIC Serializable<Safe::WString>;
701 extern template class STORMBYTE_PUBLIC Serializable<Safe::Binary>;
703}
704
705#include <StormByte/serializable.txx>
IEC octet length (uint64_t), implicit only to std::size_t.
Count of octets (uint64_t storage).
Definition byte_size.hxx:105
Deserialization failed.
Definition exception.hxx:172
Owned contiguous sequence of std::byte, stored in a Vector.
Definition binary.hxx:79
Owned UTF-8 text.
Definition string.hxx:113
Wide counterpart of String.
Definition wstring.hxx:104
Serializable(const DecayedT &data) noexcept
Binds data for a later StormByte::Serializable::Serialize.
Definition serializable.hxx:462
static ByteSize Size(const DecayedT &data) noexcept
Serialized size of data.
Safe::Binary Serialize() const noexcept
Encodes the bound value to a little-endian blob.
Serializable(const Serializable &other) noexcept=delete
Copy is deleted: the wrapper only holds a reference.
static Expected< T, DeserializeError > Deserialize(std::span< const std::byte > data) noexcept
Decodes one T from the start of data.
Serializable(Serializable &&other) noexcept=delete
Move is deleted: the wrapper only holds a reference.
~Serializable() noexcept=default
Destructor.
Same type after stripping cv and references from both sides.
Definition relations.hxx:139
Private helpers.
constexpr bool codec_always_false_v
Compile-time false dependent on T.
Definition serializable.hxx:83
STORMBYTE_FORCE_INLINE bool NextUtf8(std::string_view utf8, std::size_t &index, char32_t &cp) noexcept
One UTF-8 sequence.
Definition serializable.hxx:338
Owned values that cross a DLL without the caller's CRT.
Root namespace of the StormByte suite.
std::conditional_t< Type::Reference< T >, std::expected< std::reference_wrapper< std::remove_reference_t< T > >, Safe::Shared< E > >, std::expected< T, Safe::Shared< E > > > Expected
std::expected alias with reference and shared-error handling.
Definition expected.hxx:62
auto Unexpected(Safe::Shared< E > error)
Forwards an error already stored by Expected.
Definition expected.hxx:75
Octet count. Defined in byte_size.hxx. Forwarded so Type::Numeral can name it.
STL namespace.
#define STORMBYTE_FORCE_INLINE
Definition platform.h:134
static Expected< Safe::String, DeserializeError > Read(std::span< const std::byte > data) noexcept
Decodes a StormByte::Safe::String from the start of data.
static Safe::Binary Write(const Safe::String &data) noexcept
Encodes data.
static ByteSize Size(const Safe::String &data) noexcept
Serialized size of data.
static Expected< Safe::WString, DeserializeError > Read(std::span< const std::byte > data) noexcept
Decodes a StormByte::Safe::WString from the start of data.
static Safe::Binary Write(const Safe::WString &data) noexcept
Encodes data.
static ByteSize Size(const Safe::WString &data) noexcept
Serialized size of data.
static Safe::Binary Write(const std::string &data) noexcept
Encodes data.
static ByteSize Size(const std::string &data) noexcept
Serialized size of data.
static Safe::Binary Write(const std::u16string &data) noexcept
Encodes data.
static ByteSize Size(const std::u16string &data) noexcept
Serialized size of data.
static Safe::Binary Write(const std::u32string &data) noexcept
Encodes data.
static ByteSize Size(const std::u32string &data) noexcept
Serialized size of data.
static Safe::Binary Write(const std::wstring &data) noexcept
Encodes data.
static ByteSize Size(const std::wstring &data) noexcept
Serialized size of data.
Size / write / read for one type T.
Definition serializable.hxx:108
static ByteSize Size(const T &data) noexcept
Serialized size of data.
Definition serializable.hxx:114
static Safe::Binary Write(const T &data) noexcept
Encodes data to a little-endian blob.
Definition serializable.hxx:126
static Expected< T, DeserializeError > Read(std::span< const std::byte > data) noexcept
Decodes T from the start of data.
Definition serializable.hxx:138
#define STORMBYTE_PUBLIC
Definition visibility.h:52