StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
binary.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
46#include <StormByte/size.hxx>
48
49#include <algorithm>
50#include <compare>
51#include <cstddef>
52#include <initializer_list>
53#include <iterator>
54#include <span>
55#include <string_view>
56#include <utility>
57#include <vector>
58
63namespace StormByte {
68 namespace Safe {
80 public:
81 using value_type = std::byte;
82 using size_type = Size;
83 using difference_type = std::ptrdiff_t;
84 using reference = std::byte&;
85 using const_reference = const std::byte&;
86 using pointer = std::byte*;
87 using const_pointer = const std::byte*;
88 using iterator = std::byte*;
89 using const_iterator = const std::byte*;
90 using reverse_iterator = std::reverse_iterator<iterator>;
91 using const_reverse_iterator = std::reverse_iterator<const_iterator>;
92
96 Binary() noexcept;
97
103 Binary(const ByteSize& count, std::byte value);
104
109 explicit Binary(const ByteSize& count);
110
115 explicit Binary(std::span<const std::byte> bytes);
116
123 Binary(const std::byte* bytes, const ByteSize& count);
124
129 Binary(std::initializer_list<std::byte> list);
130
135 explicit Binary(std::string_view text);
136
141 explicit Binary(const char* text);
142
147 STORMBYTE_FORCE_INLINE explicit Binary(const std::vector<std::byte>& bytes): Binary(std::span<const std::byte>(bytes.data(), bytes.size())) {}
148
153 STORMBYTE_FORCE_INLINE explicit Binary(std::vector<std::byte>&& bytes): Binary(std::span<const std::byte>(bytes.data(), bytes.size())) {
154 bytes.clear();
155 bytes.shrink_to_fit();
156 }
157
163 template<Type::ByteInputRange R>
164 explicit Binary(const R& range);
165
171 template<Type::ByteInputRange R>
172 explicit Binary(R&& range);
173
178 Binary(const Binary& other);
179
184 Binary(Binary&& other) noexcept;
185
190 virtual ~Binary() noexcept;
191
197 Binary& operator=(const Binary& other);
198
206 Binary& operator=(Binary&& other) noexcept;
207
213 Binary& operator=(std::initializer_list<std::byte> list);
214
222 bool operator==(const Binary& other) const noexcept;
223
229 bool operator!=(const Binary& other) const noexcept;
230
236 STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(const Binary& other) const noexcept {
237 return m_bytes <=> other.m_bytes;
238 }
239
245 bool operator==(std::span<const std::byte> bytes) const noexcept;
246
252 bool operator!=(std::span<const std::byte> bytes) const noexcept;
253
259 STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(std::span<const std::byte> bytes) const noexcept {
260 return std::lexicographical_compare_three_way(span().begin(), span().end(), bytes.begin(), bytes.end());
261 }
262
267 iterator begin() noexcept;
268
273 const_iterator begin() const noexcept;
274
279 iterator end() noexcept;
280
285 const_iterator end() const noexcept;
286
291 const_iterator cbegin() const noexcept;
292
297 const_iterator cend() const noexcept;
298
304
310
316
321 const_reverse_iterator rend() const noexcept;
322
328
334
339 ByteSize size() const noexcept;
340
345 ByteSize max_size() const noexcept;
346
351 ByteSize capacity() const noexcept;
352
357 bool empty() const noexcept;
358
363 void reserve(const ByteSize& new_cap);
364
369 void resize(const ByteSize& new_size);
370
376 void resize(const ByteSize& new_size, std::byte value);
377
382
386 void clear() noexcept;
387
393 std::byte& operator[](const ByteSize& index) noexcept;
394
400 const std::byte& operator[](const ByteSize& index) const noexcept;
401
408 std::byte& at(const ByteSize& index);
409
416 const std::byte& at(const ByteSize& index) const;
417
422 std::byte& front();
423
428 const std::byte& front() const;
429
434 std::byte& back();
435
440 const std::byte& back() const;
441
446 std::byte* data() noexcept;
447
452 const std::byte* data() const noexcept;
453
459 return std::span<std::byte>(data(), static_cast<std::size_t>(size()));
460 }
461
466 STORMBYTE_FORCE_INLINE std::span<const std::byte> span() const noexcept {
467 return std::span<const std::byte>(data(), static_cast<std::size_t>(size()));
468 }
469
474 STORMBYTE_FORCE_INLINE operator std::span<std::byte>() noexcept {
475 return span();
476 }
477
482 STORMBYTE_FORCE_INLINE operator std::span<const std::byte>() const noexcept {
483 return span();
484 }
485
490 STORMBYTE_FORCE_INLINE explicit operator std::vector<std::byte>() const& {
491 const std::span<const std::byte> bytes = span();
492 return std::vector<std::byte>(bytes.begin(), bytes.end());
493 }
494
499 STORMBYTE_FORCE_INLINE explicit operator std::vector<std::byte>() && {
500 const std::span<const std::byte> bytes = span();
501 std::vector<std::byte> out(bytes.begin(), bytes.end());
502 clear();
504 return out;
505 }
506
512 void assign(const ByteSize& count, std::byte value);
513
518 void assign(std::span<const std::byte> bytes);
519
524 void assign(std::initializer_list<std::byte> list);
525
532 template<typename InputIt>
533 void assign(InputIt first, InputIt last);
534
539 void append(std::span<const std::byte> bytes);
540
547 void append(const std::byte* bytes, const ByteSize& count);
548
553 void append(const Binary& other);
554
559 void append(Binary&& other);
560
566 Binary& operator+=(std::span<const std::byte> bytes);
567
573 Binary& operator+=(const Binary& other);
574
581
586 void push_back(std::byte value);
587
594 template<typename T>
595 reference emplace_back(T&& value);
596
600 void pop_back();
601
608 iterator insert(const_iterator pos, std::byte value);
609
617 iterator insert(const_iterator pos, const ByteSize& count, std::byte value);
618
625 iterator insert(const_iterator pos, std::initializer_list<std::byte> list);
626
633 iterator insert(const_iterator pos, std::span<const std::byte> bytes);
634
643 template<typename InputIt>
644 iterator insert(const_iterator pos, InputIt first, InputIt last);
645
652
660
667 void swap(Binary& other) noexcept;
668
674
680 String HexDump(Size columns) const;
681
682 protected:
689 virtual void Discard(std::span<std::byte> bytes) noexcept;
690
695 virtual bool ConstantTimeCompare() const noexcept;
696
703 virtual void Acquire(std::span<std::byte> block) noexcept;
704
711 virtual void Release(std::span<std::byte> block) noexcept;
712
717 static void Wipe(std::span<std::byte> bytes) noexcept;
718
723 std::span<std::byte> Storage() noexcept;
724
725 private:
726 Vector<std::byte> m_bytes;
727
732 void Reallocate(std::size_t new_cap);
733
738 void Grow(std::size_t required);
739
744 void SetSize(std::size_t new_size);
745
752 std::byte* OpenGap(std::size_t offset, std::size_t count);
753 };
754
760 inline void swap(Binary& left, Binary& right) noexcept {
761 left.swap(right);
762 }
763
770 inline bool operator==(std::span<const std::byte> bytes, const Binary& data) noexcept {
771 return data == bytes;
772 }
773
780 inline bool operator!=(std::span<const std::byte> bytes, const Binary& data) noexcept {
781 return data != bytes;
782 }
783
790 STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(std::span<const std::byte> bytes, const Binary& data) noexcept {
791 return 0 <=> (data <=> bytes);
792 }
793
794 template<Type::ByteInputRange R>
795 Binary::Binary(const R& range): Binary() {
796 if constexpr (requires { std::size(range); })
797 reserve(ByteSize{std::size(range)});
798 for (auto&& byte : range)
799 push_back(static_cast<std::byte>(byte));
800 }
801
802 template<Type::ByteInputRange R>
803 Binary::Binary(R&& range): Binary() {
804 using U = std::remove_cvref_t<R>;
806 *this = std::move(static_cast<Binary&>(range));
807 } else {
808 if constexpr (requires { std::size(range); })
809 reserve(ByteSize{std::size(range)});
810 for (auto&& byte : range)
811 push_back(static_cast<std::byte>(byte));
812 }
813 }
814
815 template<typename InputIt>
816 void Binary::assign(InputIt first, InputIt last) {
817 clear();
818 for (; first != last; ++first)
819 push_back(static_cast<std::byte>(*first));
820 }
821
822 template<typename T>
824 push_back(static_cast<std::byte>(std::forward<T>(value)));
825 return back();
826 }
827
828 template<typename InputIt>
829 Binary::iterator Binary::insert(const_iterator pos, InputIt first, InputIt last) {
830 auto offset = static_cast<std::size_t>(pos - cbegin());
831 if constexpr (std::forward_iterator<InputIt>) {
832 const auto count = static_cast<std::size_t>(std::distance(first, last));
833 if (count == 0)
834 return begin() + offset;
835 std::byte* gap = OpenGap(offset, count);
836 for (std::size_t index = 0; first != last; ++first, ++index)
837 gap[index] = static_cast<std::byte>(*first);
838 return gap;
839 } else {
840 // Single-pass input: one byte at a time, so no unwiped scratch copy exists.
841 const std::size_t start = offset;
842 for (; first != last; ++first, ++offset)
843 insert(cbegin() + offset, static_cast<std::byte>(*first));
844 return begin() + start;
845 }
846 }
847 }
848}
849
853template<>
860 STORMBYTE_FORCE_INLINE std::size_t operator()(const StormByte::Safe::Binary& value) const noexcept {
861 return Safe::HashBytes(value.span());
862 }
863};
864
868template<>
869struct std::hash<StormByte::Safe::Binary> {
875 std::size_t operator()(const StormByte::Safe::Binary& value) const noexcept {
877 }
878};
IEC octet length (uint64_t), implicit only to std::size_t.
Count of octets (uint64_t storage).
Definition byte_size.hxx:105
Owned contiguous sequence of std::byte, stored in a Vector.
Definition binary.hxx:79
std::reverse_iterator< iterator > reverse_iterator
Reverse iterator.
Definition binary.hxx:90
const std::byte * const_iterator
Contiguous read-only iterator.
Definition binary.hxx:89
iterator begin() noexcept
Mutable iterator to the first byte.
reverse_iterator rbegin() noexcept
Mutable reverse iterator to the last byte.
const_reverse_iterator crend() const noexcept
Read-only reverse iterator before the first byte.
void resize(const ByteSize &new_size)
Resize to new_size bytes.
Binary & operator+=(std::span< const std::byte > bytes)
Append a copy of bytes.
Binary & operator+=(const Binary &other)
Append a copy of other.
std::byte & reference
Mutable element reference.
Definition binary.hxx:84
STORMBYTE_FORCE_INLINE Binary(std::vector< std::byte > &&bytes)
Copy bytes from a caller-owned vector, then empty it.
Definition binary.hxx:153
virtual ~Binary() noexcept
Destroy the sequence on Base's heap.
bool operator!=(std::span< const std::byte > bytes) const noexcept
Inequality with a byte span.
std::span< std::byte > Storage() noexcept
The whole allocated block, including unused capacity.
void append(Binary &&other)
Append other, then empty it.
Size size_type
Count typedef. size() returns ByteSize.
Definition binary.hxx:82
virtual bool ConstantTimeCompare() const noexcept
Whether equality must not depend on where the bytes differ.
std::byte * data() noexcept
Mutable pointer to the first byte, or null when empty.
static void Wipe(std::span< std::byte > bytes) noexcept
Zero bytes.
Binary(const Binary &other)
Copy construct.
reference emplace_back(T &&value)
Append a byte constructed in place.
Definition binary.hxx:823
void swap(Binary &other) noexcept
Exchange storage with other.
ByteSize capacity() const noexcept
Allocated capacity in bytes.
iterator insert(const_iterator pos, std::byte value)
Insert one byte before pos.
reverse_iterator rend() noexcept
Mutable reverse iterator before the first byte.
void assign(std::initializer_list< std::byte > list)
Replace contents with an initializer list.
String HexDump() const
Hexadecimal dump, sixteen bytes per row.
void reserve(const ByteSize &new_cap)
Request capacity of at least new_cap bytes.
iterator erase(const_iterator first, const_iterator last)
Erase [first, last).
const_iterator cbegin() const noexcept
Read-only iterator to the first byte.
void shrink_to_fit()
Release unused capacity when the implementation allows it.
std::byte value_type
Element type.
Definition binary.hxx:81
bool empty() const noexcept
Whether the sequence holds no bytes.
const std::byte * const_pointer
Read-only pointer.
Definition binary.hxx:87
void append(const std::byte *bytes, const ByteSize &count)
Append count bytes starting at bytes.
STORMBYTE_FORCE_INLINE std::span< std::byte > span() noexcept
Mutable view of the occupied bytes.
Definition binary.hxx:458
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(std::span< const std::byte > bytes) const noexcept
Three-way comparison with a byte span.
Definition binary.hxx:259
iterator insert(const_iterator pos, const ByteSize &count, std::byte value)
Insert count copies of value before pos.
std::byte * pointer
Mutable pointer.
Definition binary.hxx:86
void push_back(std::byte value)
Append one byte.
Binary(Binary &&other) noexcept
Move construct.
std::reverse_iterator< const_iterator > const_reverse_iterator
Read-only reverse iterator.
Definition binary.hxx:91
iterator insert(const_iterator pos, std::span< const std::byte > bytes)
Insert a span before pos.
void clear() noexcept
Drop every byte.
String HexDump(Size columns) const
Hexadecimal dump of the occupied bytes.
void append(std::span< const std::byte > bytes)
Append a copy of bytes.
void append(const Binary &other)
Append a copy of other.
ByteSize size() const noexcept
Occupied length in bytes.
bool operator==(std::span< const std::byte > bytes) const noexcept
Equality with a byte span.
std::ptrdiff_t difference_type
Iterator difference.
Definition binary.hxx:83
const std::byte & const_reference
Read-only element reference.
Definition binary.hxx:85
void assign(const ByteSize &count, std::byte value)
Replace contents with count copies of value.
Binary & operator+=(Binary &&other)
Append other, then empty it.
iterator insert(const_iterator pos, std::initializer_list< std::byte > list)
Insert an initializer list before pos.
STORMBYTE_FORCE_INLINE std::span< const std::byte > span() const noexcept
Read-only view of the occupied bytes.
Definition binary.hxx:466
void pop_back()
Remove the last byte.
virtual void Release(std::span< std::byte > block) noexcept
Called when a block stops being owned by this object: the old block after a reallocation,...
virtual void Discard(std::span< std::byte > bytes) noexcept
Called with every byte range this sequence is about to drop or release.
std::byte & back()
Last byte.
Binary() noexcept
Construct an empty sequence.
const_reverse_iterator crbegin() const noexcept
Read-only reverse iterator to the last byte.
ByteSize max_size() const noexcept
Implementation maximum size in bytes.
iterator erase(const_iterator pos)
Erase the byte at pos.
std::byte * iterator
Contiguous mutable iterator.
Definition binary.hxx:88
std::byte & at(const ByteSize &index)
Checked mutable subscript.
iterator end() noexcept
Mutable iterator one past the last byte.
const_iterator cend() const noexcept
Read-only iterator one past the last byte.
void assign(std::span< const std::byte > bytes)
Replace contents with a copy of bytes.
virtual void Acquire(std::span< std::byte > block) noexcept
Called when an allocated block becomes owned by this object: a new block on growth or shrinking,...
std::byte & front()
First byte.
Owned UTF-8 text.
Definition string.hxx:113
Contiguous sequence stored on Base's heap.
Definition vector.hxx:81
Count of abstract units (uint64_t storage).
Definition size.hxx:107
Derived derives from Base (std::is_base_of).
Definition relations.hxx:156
Lvalue reference type (std::is_lvalue_reference).
Definition categories.hxx:97
Owned values that cross a DLL without the caller's CRT.
bool operator==(std::span< const std::byte > bytes, const Binary &data) noexcept
Equality of a span against a sequence.
Definition binary.hxx:770
bool operator!=(std::span< const std::byte > bytes, const Binary &data) noexcept
Inequality of a span against a sequence.
Definition binary.hxx:780
void swap(Binary &left, Binary &right) noexcept
Exchange two sequences.
Definition binary.hxx:760
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(std::span< const std::byte > bytes, const Binary &data) noexcept
Three-way comparison of a span against a sequence.
Definition binary.hxx:790
STORMBYTE_FORCE_INLINE std::size_t HashBytes(std::span< const std::byte > bytes) noexcept
Mix a byte range with FNV-1a.
Definition hash.hxx:66
Root namespace of the StormByte suite.
STL namespace.
#define STORMBYTE_FORCE_INLINE
Definition platform.h:134
Host-width-stable count (uint64_t), implicit only to std::size_t.
STORMBYTE_FORCE_INLINE std::size_t operator()(const StormByte::Safe::Binary &value) const noexcept
Hashes value.
Definition binary.hxx:860
Cross-module hash.
Definition hash.hxx:95
std::size_t operator()(const StormByte::Safe::Binary &value) const noexcept
Hashes value.
Definition binary.hxx:875
#define STORMBYTE_PUBLIC
Definition visibility.h:52