Owned contiguous sequence of std::byte, stored in a Vector.
More...
#include <StormByte/safe/binary.hxx>

Public Types | |
| using | value_type = std::byte |
| Element type. | |
| using | size_type = Size |
| Count typedef. size() returns ByteSize. | |
| using | difference_type = std::ptrdiff_t |
| Iterator difference. | |
| using | reference = std::byte& |
| Mutable element reference. | |
| using | const_reference = const std::byte& |
| Read-only element reference. | |
| using | pointer = std::byte* |
| Mutable pointer. | |
| using | const_pointer = const std::byte* |
| Read-only pointer. | |
| using | iterator = std::byte* |
| Contiguous mutable iterator. | |
| using | const_iterator = const std::byte* |
| Contiguous read-only iterator. | |
| using | reverse_iterator = std::reverse_iterator<iterator> |
| Reverse iterator. | |
| using | const_reverse_iterator = std::reverse_iterator<const_iterator> |
| Read-only reverse iterator. | |
Public Member Functions | |
| Binary () noexcept | |
| Construct an empty sequence. | |
| Binary (const ByteSize &count, std::byte value) | |
Construct count bytes filled with value. | |
| Binary (const ByteSize &count) | |
Construct count zeroed bytes. | |
| Binary (std::span< const std::byte > bytes) | |
| Copy bytes from a contiguous span. | |
| Binary (const std::byte *bytes, const ByteSize &count) | |
Copy count bytes starting at bytes. | |
| Binary (std::initializer_list< std::byte > list) | |
| Copy from an initializer list. | |
| Binary (std::string_view text) | |
| Copy character bytes from a string view. | |
| Binary (const char *text) | |
| Copy character bytes from a C string. | |
| STORMBYTE_FORCE_INLINE | Binary (const std::vector< std::byte > &bytes) |
| Copy bytes from a caller-owned vector. | |
| STORMBYTE_FORCE_INLINE | Binary (std::vector< std::byte > &&bytes) |
| Copy bytes from a caller-owned vector, then empty it. | |
| template<Type::ByteInputRange R> | |
| Binary (const R &range) | |
| Copy from an input range of byte-convertible values. | |
| template<Type::ByteInputRange R> | |
| Binary (R &&range) | |
| Consume an rvalue range. | |
| Binary (const Binary &other) | |
| Copy construct. | |
| Binary (Binary &&other) noexcept | |
| Move construct. | |
| virtual | ~Binary () noexcept |
| Destroy the sequence on Base's heap. | |
| Binary & | operator= (const Binary &other) |
| Copy assign. | |
| Binary & | operator= (Binary &&other) noexcept |
| Move assign. | |
| Binary & | operator= (std::initializer_list< std::byte > list) |
| Replace contents with an initializer list. | |
| bool | operator== (const Binary &other) const noexcept |
| Equality of byte contents. | |
| bool | operator!= (const Binary &other) const noexcept |
| Inequality of byte contents. | |
| STORMBYTE_FORCE_INLINE std::strong_ordering | operator<=> (const Binary &other) const noexcept |
| Three-way lexicographical comparison. | |
| bool | operator== (std::span< const std::byte > bytes) const noexcept |
| Equality with a byte span. | |
| bool | operator!= (std::span< const std::byte > bytes) const noexcept |
| Inequality with a byte span. | |
| STORMBYTE_FORCE_INLINE std::strong_ordering | operator<=> (std::span< const std::byte > bytes) const noexcept |
| Three-way comparison with a byte span. | |
| iterator | begin () noexcept |
| Mutable iterator to the first byte. | |
| const_iterator | begin () const noexcept |
| Read-only iterator to the first byte. | |
| iterator | end () noexcept |
| Mutable iterator one past the last byte. | |
| const_iterator | end () const noexcept |
| Read-only iterator one past the last byte. | |
| const_iterator | cbegin () const noexcept |
| Read-only iterator to the first byte. | |
| const_iterator | cend () const noexcept |
| Read-only iterator one past the last byte. | |
| reverse_iterator | rbegin () noexcept |
| Mutable reverse iterator to the last byte. | |
| reverse_iterator | rend () noexcept |
| Mutable reverse iterator before the first byte. | |
| const_reverse_iterator | rbegin () const noexcept |
| Read-only reverse iterator to the last byte. | |
| const_reverse_iterator | rend () const noexcept |
| Read-only reverse iterator before the first byte. | |
| const_reverse_iterator | crbegin () const noexcept |
| Read-only reverse iterator to the last byte. | |
| const_reverse_iterator | crend () const noexcept |
| Read-only reverse iterator before the first byte. | |
| ByteSize | size () const noexcept |
| Occupied length in bytes. | |
| ByteSize | max_size () const noexcept |
| Implementation maximum size in bytes. | |
| ByteSize | capacity () const noexcept |
| Allocated capacity in bytes. | |
| bool | empty () const noexcept |
| Whether the sequence holds no bytes. | |
| void | reserve (const ByteSize &new_cap) |
Request capacity of at least new_cap bytes. | |
| void | resize (const ByteSize &new_size) |
Resize to new_size bytes. | |
| void | resize (const ByteSize &new_size, std::byte value) |
Resize to new_size bytes. | |
| void | shrink_to_fit () |
| Release unused capacity when the implementation allows it. | |
| void | clear () noexcept |
| Drop every byte. | |
| std::byte & | operator[] (const ByteSize &index) noexcept |
| Unchecked mutable subscript. | |
| const std::byte & | operator[] (const ByteSize &index) const noexcept |
| Unchecked read-only subscript. | |
| std::byte & | at (const ByteSize &index) |
| Checked mutable subscript. | |
| const std::byte & | at (const ByteSize &index) const |
| Checked read-only subscript. | |
| std::byte & | front () |
| First byte. | |
| const std::byte & | front () const |
| First byte. | |
| std::byte & | back () |
| Last byte. | |
| const std::byte & | back () const |
| Last byte. | |
| std::byte * | data () noexcept |
| Mutable pointer to the first byte, or null when empty. | |
| const std::byte * | data () const noexcept |
| Read-only pointer to the first byte, or null when empty. | |
| STORMBYTE_FORCE_INLINE std::span< std::byte > | span () noexcept |
| Mutable view of the occupied bytes. | |
| STORMBYTE_FORCE_INLINE std::span< const std::byte > | span () const noexcept |
| Read-only view of the occupied bytes. | |
| STORMBYTE_FORCE_INLINE | operator std::span< std::byte > () noexcept |
| Implicit mutable span conversion. | |
| STORMBYTE_FORCE_INLINE | operator std::span< const std::byte > () const noexcept |
| Implicit read-only span conversion. | |
| STORMBYTE_FORCE_INLINE | operator std::vector< std::byte > () const & |
| Copy bytes onto the caller CRT as a vector. | |
| STORMBYTE_FORCE_INLINE | operator std::vector< std::byte > () && |
| Copy bytes onto the caller CRT, then release this object's storage. | |
| void | assign (const ByteSize &count, std::byte value) |
Replace contents with count copies of value. | |
| void | assign (std::span< const std::byte > bytes) |
Replace contents with a copy of bytes. | |
| void | assign (std::initializer_list< std::byte > list) |
| Replace contents with an initializer list. | |
| template<typename InputIt> | |
| void | assign (InputIt first, InputIt last) |
| Replace contents with the range [first, last). | |
| void | append (std::span< const std::byte > bytes) |
Append a copy of bytes. | |
| void | append (const std::byte *bytes, const ByteSize &count) |
Append count bytes starting at bytes. | |
| void | append (const Binary &other) |
Append a copy of other. | |
| void | append (Binary &&other) |
Append other, then empty it. | |
| Binary & | operator+= (std::span< const std::byte > bytes) |
Append a copy of bytes. | |
| Binary & | operator+= (const Binary &other) |
Append a copy of other. | |
| Binary & | operator+= (Binary &&other) |
Append other, then empty it. | |
| void | push_back (std::byte value) |
| Append one byte. | |
| template<typename T> | |
| reference | emplace_back (T &&value) |
| Append a byte constructed in place. | |
| void | pop_back () |
| Remove the last byte. | |
| iterator | insert (const_iterator pos, std::byte value) |
Insert one byte before pos. | |
| iterator | insert (const_iterator pos, const ByteSize &count, std::byte value) |
Insert count copies of value before pos. | |
| iterator | insert (const_iterator pos, std::initializer_list< std::byte > list) |
Insert an initializer list before pos. | |
| iterator | insert (const_iterator pos, std::span< const std::byte > bytes) |
Insert a span before pos. | |
| template<typename InputIt> | |
| iterator | insert (const_iterator pos, InputIt first, InputIt last) |
Insert the range [first, last) before pos. | |
| iterator | erase (const_iterator pos) |
Erase the byte at pos. | |
| iterator | erase (const_iterator first, const_iterator last) |
| Erase [first, last). | |
| void | swap (Binary &other) noexcept |
Exchange storage with other. | |
| String | HexDump () const |
| Hexadecimal dump, sixteen bytes per row. | |
| String | HexDump (Size columns) const |
| Hexadecimal dump of the occupied bytes. | |
Protected Member Functions | |
| virtual void | Discard (std::span< std::byte > bytes) noexcept |
| Called with every byte range this sequence is about to drop or release. | |
| virtual bool | ConstantTimeCompare () const noexcept |
| Whether equality must not depend on where the bytes differ. | |
| 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, or a block taken from another sequence by move assignment or swap. | |
| 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, or a block handed to another sequence by a move or swap. | |
| std::span< std::byte > | Storage () noexcept |
| The whole allocated block, including unused capacity. | |
Static Protected Member Functions | |
| static void | Wipe (std::span< std::byte > bytes) noexcept |
Zero bytes. | |
Owned contiguous sequence of std::byte, stored in a Vector.
There is no separate backend. Bytes live in Vector of std::byte, allocated with Heap::Allocate. Names match std::vector. Length, capacity and offsets are ByteSize. A hex-dump column count is Size.
A conversion to std::vector copies into the caller. It does not steal the Base pointer. An rvalue overload empties this object after the copy.
The class can be derived. Every byte the sequence drops is first passed to Discard: erased or popped bytes, the shrunk tail, previous contents on assign, and the whole old block when the storage is reallocated. Every allocated block that enters or leaves the object, by reallocation, move or swap, goes through Acquire and Release. SecureBinary overrides them to zero the bytes and lock the pages. A plain Binary does nothing there.
| using StormByte::Safe::Binary::const_iterator = const std::byte* |
Contiguous read-only iterator.
| using StormByte::Safe::Binary::const_pointer = const std::byte* |
Read-only pointer.
| using StormByte::Safe::Binary::const_reference = const std::byte& |
Read-only element reference.
| using StormByte::Safe::Binary::const_reverse_iterator = std::reverse_iterator<const_iterator> |
Read-only reverse iterator.
| using StormByte::Safe::Binary::difference_type = std::ptrdiff_t |
Iterator difference.
| using StormByte::Safe::Binary::iterator = std::byte* |
Contiguous mutable iterator.
| using StormByte::Safe::Binary::pointer = std::byte* |
Mutable pointer.
| using StormByte::Safe::Binary::reference = std::byte& |
Mutable element reference.
| using StormByte::Safe::Binary::reverse_iterator = std::reverse_iterator<iterator> |
Reverse iterator.
| using StormByte::Safe::Binary::value_type = std::byte |
Element type.
|
noexcept |
Construct an empty sequence.
| StormByte::Safe::Binary::Binary | ( | const ByteSize & | count, |
| std::byte | value ) |
Construct count bytes filled with value.
| count | Element count. |
| value | Fill byte. |
|
explicit |
Construct count zeroed bytes.
| count | Element count. |
|
explicit |
Copy bytes from a contiguous span.
| bytes | Source view. Not owned. |
| StormByte::Safe::Binary::Binary | ( | const std::byte * | bytes, |
| const ByteSize & | count ) |
Copy count bytes starting at bytes.
| bytes | Source pointer. May be null when count is zero. |
| count | Byte count. |
| OutOfBoundsError | bytes is null and count is not zero. |
| StormByte::Safe::Binary::Binary | ( | std::initializer_list< std::byte > | list | ) |
Copy from an initializer list.
| list | Source bytes. |
|
explicit |
Copy character bytes from a string view.
No trailing NUL.
| text | Source characters. |
|
explicit |
Copy character bytes from a C string.
No trailing NUL.
| text | Source. A null pointer yields an empty sequence. |
|
inlineexplicit |
Copy bytes from a caller-owned vector.
The vector is unchanged.
| bytes | Source. |
|
inlineexplicit |
Copy bytes from a caller-owned vector, then empty it.
| bytes | Source. Cleared after the copy. Not a heap steal. |
|
explicit |
Copy from an input range of byte-convertible values.
| R | Range type satisfying Type::ByteInputRange. |
| range | Source range. |
|
explicit |
Consume an rvalue range.
Moves when R is an rvalue Binary.
| R | Range type satisfying Type::ByteInputRange. |
| range | Source range. |
| StormByte::Safe::Binary::Binary | ( | const Binary & | other | ) |
Copy construct.
| other | Source sequence. |
|
noexcept |
|
virtualnoexcept |
|
protectedvirtualnoexcept |
Called when an allocated block becomes owned by this object: a new block on growth or shrinking, or a block taken from another sequence by move assignment or swap.
Called before the bytes are copied in. Every block passed here is later passed once to Release, unless this object is destroyed while owning it. Default does nothing. Not called from constructors: a derived constructor that takes a block from its base calls it itself.
| block | Whole block, including unused capacity. |
Reimplemented in StormByte::Safe::SecureBinary.
| void StormByte::Safe::Binary::append | ( | Binary && | other | ) |
Append other, then empty it.
| other | Source sequence. Empty afterwards when it is not this object. |
| void StormByte::Safe::Binary::append | ( | const Binary & | other | ) |
Append a copy of other.
| other | Source sequence. |
| void StormByte::Safe::Binary::append | ( | const std::byte * | bytes, |
| const ByteSize & | count ) |
Append count bytes starting at bytes.
| bytes | Source pointer. May be null when count is zero. |
| count | Byte count. |
| OutOfBoundsError | bytes is null and count is not zero. |
| void StormByte::Safe::Binary::append | ( | std::span< const std::byte > | bytes | ) |
Append a copy of bytes.
| bytes | Source view. |
| void StormByte::Safe::Binary::assign | ( | const ByteSize & | count, |
| std::byte | value ) |
Replace contents with count copies of value.
| count | New size. |
| value | Fill byte. |
| void StormByte::Safe::Binary::assign | ( | InputIt | first, |
| InputIt | last ) |
Replace contents with the range [first, last).
| InputIt | Input iterator whose value converts to std::byte. |
| first | Start of the source range. |
| last | End of the source range. |
| void StormByte::Safe::Binary::assign | ( | std::initializer_list< std::byte > | list | ) |
Replace contents with an initializer list.
| list | Source bytes. |
| void StormByte::Safe::Binary::assign | ( | std::span< const std::byte > | bytes | ) |
Replace contents with a copy of bytes.
| bytes | Source view. |
| std::byte & StormByte::Safe::Binary::at | ( | const ByteSize & | index | ) |
Checked mutable subscript.
| index | Byte offset. |
index. | OutOfBoundsError | index is not less than size(). |
| const std::byte & StormByte::Safe::Binary::at | ( | const ByteSize & | index | ) | const |
Checked read-only subscript.
| index | Byte offset. |
index. | OutOfBoundsError | index is not less than size(). |
| std::byte & StormByte::Safe::Binary::back | ( | ) |
Last byte.
| const std::byte & StormByte::Safe::Binary::back | ( | ) | const |
Last byte.
|
noexcept |
Read-only iterator to the first byte.
|
noexcept |
Mutable iterator to the first byte.
|
noexcept |
Allocated capacity in bytes.
|
noexcept |
Read-only iterator to the first byte.
|
noexcept |
Read-only iterator one past the last byte.
|
noexcept |
Drop every byte.
Capacity may remain.
|
protectedvirtualnoexcept |
Whether equality must not depend on where the bytes differ.
Reimplemented in StormByte::Safe::SecureBinary.
|
noexcept |
Read-only reverse iterator to the last byte.
|
noexcept |
Read-only reverse iterator before the first byte.
|
noexcept |
Read-only pointer to the first byte, or null when empty.
|
noexcept |
Mutable pointer to the first byte, or null when empty.
|
protectedvirtualnoexcept |
Called with every byte range this sequence is about to drop or release.
Default does nothing. Not called from constructors or from the destructor, where the call would not reach the derived class.
| bytes | Bytes to dispose of. They stay owned by this object. |
Reimplemented in StormByte::Safe::SecureBinary.
| Binary::reference StormByte::Safe::Binary::emplace_back | ( | T && | value | ) |
Append a byte constructed in place.
| T | Value convertible to std::byte. |
| value | Argument forwarded into std::byte. |
|
noexcept |
Whether the sequence holds no bytes.
|
noexcept |
Read-only iterator one past the last byte.
|
noexcept |
Mutable iterator one past the last byte.
| iterator StormByte::Safe::Binary::erase | ( | const_iterator | first, |
| const_iterator | last ) |
Erase [first, last).
| first | Start of the range. |
| last | End of the range. |
| iterator StormByte::Safe::Binary::erase | ( | const_iterator | pos | ) |
Erase the byte at pos.
| pos | Byte to erase. |
| std::byte & StormByte::Safe::Binary::front | ( | ) |
First byte.
| const std::byte & StormByte::Safe::Binary::front | ( | ) | const |
First byte.
| String StormByte::Safe::Binary::HexDump | ( | ) | const |
Hexadecimal dump, sixteen bytes per row.
Hexadecimal dump of the occupied bytes.
| columns | Bytes per row. Zero means a single row. This is a count, not a ByteSize. |
| iterator StormByte::Safe::Binary::insert | ( | const_iterator | pos, |
| const ByteSize & | count, | ||
| std::byte | value ) |
Insert count copies of value before pos.
| pos | Insertion point. |
| count | Number of bytes. |
| value | Fill byte. |
pos when count is zero. | Binary::iterator StormByte::Safe::Binary::insert | ( | const_iterator | pos, |
| InputIt | first, | ||
| InputIt | last ) |
Insert the range [first, last) before pos.
| InputIt | Input iterator whose value converts to std::byte. |
| pos | Insertion point. |
| first | Start of the source range. |
| last | End of the source range. |
pos when the range is empty. | iterator StormByte::Safe::Binary::insert | ( | const_iterator | pos, |
| std::byte | value ) |
Insert one byte before pos.
| pos | Insertion point. |
| value | Byte to insert. |
| iterator StormByte::Safe::Binary::insert | ( | const_iterator | pos, |
| std::initializer_list< std::byte > | list ) |
Insert an initializer list before pos.
| pos | Insertion point. |
| list | Source bytes. |
pos when list is empty. | iterator StormByte::Safe::Binary::insert | ( | const_iterator | pos, |
| std::span< const std::byte > | bytes ) |
Insert a span before pos.
| pos | Insertion point. |
| bytes | Source view. |
pos when bytes is empty.
|
noexcept |
Implementation maximum size in bytes.
|
inlinenoexcept |
Implicit read-only span conversion.
|
inlinenoexcept |
Implicit mutable span conversion.
|
inlineexplicit |
Copy bytes onto the caller CRT, then release this object's storage.
|
inlineexplicit |
Copy bytes onto the caller CRT as a vector.
This object is unchanged.
|
noexcept |
Inequality of byte contents.
| other | Other sequence. |
|
noexcept |
Inequality with a byte span.
| bytes | View to compare. |
Append other, then empty it.
| other | Source sequence. |
Append a copy of other.
| other | Source sequence. |
| Binary & StormByte::Safe::Binary::operator+= | ( | std::span< const std::byte > | bytes | ) |
Append a copy of bytes.
| bytes | Source view. |
|
inlinenoexcept |
Three-way lexicographical comparison.
Header-only: std::strong_ordering is not a DLL ABI.
| other | Other sequence. |
|
inlinenoexcept |
Three-way comparison with a byte span.
Header-only: std::strong_ordering is not a DLL ABI.
| bytes | View to compare. |
Move assign.
other is left empty.
The previous block of this object goes through Discard before it is released. The storage of other is taken as is, even when other is a SecureBinary.
| other | Source sequence. |
Copy assign.
| other | Source sequence. |
| Binary & StormByte::Safe::Binary::operator= | ( | std::initializer_list< std::byte > | list | ) |
Replace contents with an initializer list.
| list | Source bytes. |
|
noexcept |
Equality of byte contents.
Runs in time independent of the contents when either side reports ConstantTimeCompare. Sizes are compared first and are not secret.
| other | Other sequence. |
|
noexcept |
Equality with a byte span.
Constant time when ConstantTimeCompare is true.
| bytes | View to compare. |
|
noexcept |
Unchecked read-only subscript.
| index | Byte offset. |
index.
|
noexcept |
Unchecked mutable subscript.
| index | Byte offset. |
index. | void StormByte::Safe::Binary::pop_back | ( | ) |
Remove the last byte.
| void StormByte::Safe::Binary::push_back | ( | std::byte | value | ) |
Append one byte.
| value | Byte to append. |
|
noexcept |
Read-only reverse iterator to the last byte.
|
noexcept |
Mutable reverse iterator to the last byte.
|
protectedvirtualnoexcept |
Called when a block stops being owned by this object: the old block after a reallocation, or a block handed to another sequence by a move or swap.
The block may still be alive and owned by the other sequence. Called after Discard. Default does nothing. Not called from the destructor: a derived destructor releases its own block.
| block | Whole block, as passed to Acquire. |
Reimplemented in StormByte::Safe::SecureBinary.
|
noexcept |
Read-only reverse iterator before the first byte.
|
noexcept |
Mutable reverse iterator before the first byte.
| void StormByte::Safe::Binary::reserve | ( | const ByteSize & | new_cap | ) |
Request capacity of at least new_cap bytes.
| new_cap | Requested capacity. |
| void StormByte::Safe::Binary::resize | ( | const ByteSize & | new_size | ) |
Resize to new_size bytes.
Appended bytes are zero.
| new_size | New size. |
| void StormByte::Safe::Binary::resize | ( | const ByteSize & | new_size, |
| std::byte | value ) |
Resize to new_size bytes.
Appended bytes are value.
| new_size | New size. |
| value | Fill for new bytes. |
| void StormByte::Safe::Binary::shrink_to_fit | ( | ) |
Release unused capacity when the implementation allows it.
|
noexcept |
Occupied length in bytes.
|
inlinenoexcept |
Read-only view of the occupied bytes.
|
inlinenoexcept |
Mutable view of the occupied bytes.
|
protectednoexcept |
The whole allocated block, including unused capacity.
|
noexcept |
Exchange storage with other.
The blocks are swapped, not copied. Swapping a SecureBinary with a plain Binary moves the secret into the plain object.
| other | Other sequence. |
|
staticprotectednoexcept |
Zero bytes.
The compiler cannot drop the writes.
| bytes | Bytes to zero. |