StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
StormByte Namespace Reference

Root namespace of the StormByte suite. More...

Namespaces

namespace  Error
 Error-code domains and the StormByte::Error::Fault value type.
namespace  Safe
 Owned values that cross a DLL without the caller's CRT.
namespace  Type
 Named concepts and small type utilities used across the suite.
namespace  Detail
 Private specialization point for non-trivial types.
namespace  Test

Classes

class  Bitmask
 CRTP wrapper that stores an unsigned enum as a flag set. More...
class  ByteSize
 Count of octets (uint64_t storage). More...
class  Exception
 Base exception type for the suite. More...
class  DeserializeError
 Deserialization failed. More...
class  OperationError
 An operation failed with an exception outside the StormByte hierarchy. More...
class  Base64Error
 Base64 encode or decode failed. More...
class  Serializable
 Encodes and decodes one value of type T. More...
class  Size
 Count of abstract units (uint64_t storage). More...
class  Clock
 Thread-safe aggregate of independently timed operation samples. More...
class  Telemetry
 Abstract session telemetry base with a protected clock drawer. More...
class  ThreadLock
 Mutex with owner-thread reentry. More...

Typedefs

template<typename T, class E>
using Expected
 std::expected alias with reference and shared-error handling.

Functions

Safe::Binary Base64Decode (std::string_view input)
 Decodes Base64 text into bytes.
Safe::String Base64Encode (const Safe::Binary &input)
 Encodes bytes as Base64 with = padding.
Safe::String Base64Encode (std::span< const std::byte > input)
 Encodes a contiguous byte span as Base64 with = padding.
template<Type::Integral T>
constexpr bool operator== (ByteSize lhs, T rhs)
 Mixed equality.
template<Type::Integral T>
constexpr bool operator== (T lhs, ByteSize rhs)
 Mixed equality.
template<Type::Integral T>
constexpr ByteSize operator+ (ByteSize lhs, T rhs)
 Mixed sum.
template<Type::Integral T>
constexpr ByteSize operator+ (T lhs, ByteSize rhs)
 Mixed sum.
template<Type::Integral T>
constexpr ByteSize operator- (ByteSize lhs, T rhs)
 Mixed difference.
template<Type::Integral T>
constexpr ByteSize operator- (T lhs, ByteSize rhs)
 Mixed difference.
template<Type::Integral T>
constexpr ByteSize operator* (ByteSize lhs, T rhs)
 Mixed product.
template<Type::Integral T>
constexpr ByteSize operator* (T lhs, ByteSize rhs)
 Mixed product.
template<Type::Integral T>
constexpr ByteSize operator/ (ByteSize lhs, T rhs)
 Mixed quotient.
template<Type::Integral T>
constexpr ByteSize operator% (ByteSize lhs, T rhs)
 Mixed remainder.
std::ostream & operator<< (std::ostream &stream, ByteSize size)
 Writes the IEC human-readable length.
template<typename E>
auto Unexpected (Safe::Shared< E > error)
 Forwards an error already stored by Expected.
template<typename E>
auto Unexpected (std::shared_ptr< E >)=delete
 Rejects a std::shared_ptr.
template<typename E>
requires ( !requires { typename std::remove_cvref_t<E>::element_type; } || !Type::SameAs<std::remove_cvref_t<E>, Safe::Shared<typename std::remove_cvref_t<E>::element_type>> )
auto Unexpected (E &&error)
 Builds std::unexpected by constructing E.
template<typename Base, typename Derived>
requires Type::DerivedFrom<std::decay_t<Derived>, Base> && (!Type::SameAs<Base, std::decay_t<Derived>>)
auto Unexpected (Derived &&error) -> std::unexpected< Safe::Shared< Base > >
 Builds std::unexpected from a derived error.
template<typename E, typename... Args>
auto Unexpected (const std::string &fmt, Args &&... args)
 Builds std::unexpected from a format string and E(string).
void append_bytes (Safe::Binary &dest, std::span< const std::byte > src) noexcept
 Appends a span of bytes onto a Safe::Binary.
void append_bytes (Safe::Binary &dest, const Safe::Binary &src) noexcept
 Appends a Safe::Binary by copy.
void append_bytes (Safe::Binary &dest, Safe::Binary &&src) noexcept
 Appends a Safe::Binary by move on Base's heap.
template<Type::Integral T>
constexpr bool operator== (Size lhs, T rhs)
 Mixed equality.
template<Type::Integral T>
constexpr bool operator== (T lhs, Size rhs)
 Mixed equality.
template<Type::Integral T>
constexpr Size operator+ (Size lhs, T rhs)
 Mixed sum.
template<Type::Integral T>
constexpr Size operator+ (T lhs, Size rhs)
 Mixed sum.
template<Type::Integral T>
constexpr Size operator- (Size lhs, T rhs)
 Mixed difference.
template<Type::Integral T>
constexpr Size operator- (T lhs, Size rhs)
 Mixed difference.
template<Type::Integral T>
constexpr Size operator* (Size lhs, T rhs)
 Mixed product.
template<Type::Integral T>
constexpr Size operator* (T lhs, Size rhs)
 Mixed product.
template<Type::Integral T>
constexpr Size operator/ (Size lhs, T rhs)
 Mixed quotient.
template<Type::Integral T>
constexpr Size operator/ (T lhs, Size rhs)
 Mixed quotient.
template<Type::Integral T>
constexpr Size operator% (Size lhs, T rhs)
 Mixed remainder.
template<Type::Integral T>
constexpr Size operator% (T lhs, Size rhs)
 Mixed remainder.
std::ostream & operator<< (std::ostream &stream, Size size)
 Writes the decimal count.
Safe::String GenerateUUIDv4 () noexcept
 RFC 4122 UUID version 4 (lowercase).

Variables

constexpr ByteSize B {1ull}
 One octet.
constexpr ByteSize KiB {1024ull}
 2^10 octets.
constexpr ByteSize MiB {1024ull * 1024}
 2^20 octets.
constexpr ByteSize GiB {1024ull * 1024 * 1024}
 2^30 octets.
constexpr ByteSize TiB {1024ull * 1024 * 1024 * 1024}
 2^40 octets.
constexpr ByteSize PiB {1024ull * 1024 * 1024 * 1024 * 1024}
 2^50 octets.
constexpr ByteSize EiB {1024ull * 1024 * 1024 * 1024 * 1024 * 1024}
 2^60 octets.
constexpr ByteSize KB {1000ull}
 10^3 octets.
constexpr ByteSize MB {1000ull * 1000}
 10^6 octets.
constexpr ByteSize GB {1000ull * 1000 * 1000}
 10^9 octets.
constexpr ByteSize TB {1000ull * 1000 * 1000 * 1000}
 10^12 octets.
constexpr ByteSize PB {1000ull * 1000 * 1000 * 1000 * 1000}
 10^15 octets.
constexpr ByteSize EB {1000ull * 1000 * 1000 * 1000 * 1000 * 1000}
 10^18 octets.

Detailed Description

Root namespace of the StormByte suite.

Typedef Documentation

◆ Expected

template<typename T, class E>
using StormByte::Expected
Initial value:
std::conditional_t<
std::expected<std::reference_wrapper<std::remove_reference_t<T>>, Safe::Shared<E>>,
std::expected<T, Safe::Shared<E>>
>
Forward declaration of shared ownership.
Definition pointers.hxx:133
Lvalue or rvalue reference type.
Definition categories.hxx:81

std::expected alias with reference and shared-error handling.

Template Parameters
TValue type. References are stored as std::reference_wrapper.
EError type. Always stored as Safe::Shared. Converts to std::shared_ptr<E>.

Function Documentation

◆ append_bytes() [1/3]

void StormByte::append_bytes ( Safe::Binary & dest,
const Safe::Binary & src )
inlinenoexcept

Appends a Safe::Binary by copy.

Parameters
destDestination owned by Base.
srcSource sequence (read-only).

◆ append_bytes() [2/3]

void StormByte::append_bytes ( Safe::Binary & dest,
Safe::Binary && src )
inlinenoexcept

Appends a Safe::Binary by move on Base's heap.

Parameters
destDestination owned by Base.
srcSource sequence; emptied after a successful append.

◆ append_bytes() [3/3]

void StormByte::append_bytes ( Safe::Binary & dest,
std::span< const std::byte > src )
inlinenoexcept

Appends a span of bytes onto a Safe::Binary.

Parameters
destDestination owned by Base.
srcView over the bytes to copy.

◆ Base64Decode()

Safe::Binary StormByte::Base64Decode ( std::string_view input)

Decodes Base64 text into bytes.

Alphabet A–Z a–z 0–9 + / and padding =. Space, tab, newline and CR are ignored. Decoding stops at the first =. Padding is accepted but not strictly checked.

Parameters
inputBase64 text (std::string_view, std::string or a string literal).
Returns
Decoded bytes owned by Base.
Exceptions
StormByte::Base64ErrorIf a character is outside the alphabet.

◆ Base64Encode() [1/2]

Safe::String StormByte::Base64Encode ( const Safe::Binary & input)

Encodes bytes as Base64 with = padding.

Parameters
inputBytes to encode.
Returns
Base64 text as a Safe::String.

◆ Base64Encode() [2/2]

Safe::String StormByte::Base64Encode ( std::span< const std::byte > input)

Encodes a contiguous byte span as Base64 with = padding.

Parameters
inputBytes to encode.
Returns
Base64 text as a Safe::String.

◆ GenerateUUIDv4()

Safe::String StormByte::GenerateUUIDv4 ( )
noexcept

RFC 4122 UUID version 4 (lowercase).

Returns
36-character Safe::String xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx where y is 8, 9, a or b.
Note
Prefers the OS CSPRNG; falls back to a PRNG. Details in uuid.cxx.

◆ operator%() [1/3]

template<Type::Integral T>
ByteSize StormByte::operator% ( ByteSize lhs,
T rhs )
constexprnoexcept

Mixed remainder.

Template Parameters
TIntegral type.
Parameters
lhsDividend.
rhsDivisor.
Returns
Remainder as ByteSize.

◆ operator%() [2/3]

template<Type::Integral T>
Size StormByte::operator% ( Size lhs,
T rhs )
constexprnoexcept

Mixed remainder.

Template Parameters
TIntegral type.
Parameters
lhsDividend.
rhsDivisor.
Returns
Remainder as Size.

◆ operator%() [3/3]

template<Type::Integral T>
Size StormByte::operator% ( T lhs,
Size rhs )
constexprnoexcept

Mixed remainder.

Template Parameters
TIntegral type.
Parameters
lhsDividend.
rhsDivisor.
Returns
Remainder as Size.

◆ operator*() [1/4]

template<Type::Integral T>
ByteSize StormByte::operator* ( ByteSize lhs,
T rhs )
constexprnoexcept

Mixed product.

Template Parameters
TIntegral type.
Parameters
lhsLeft factor.
rhsRight factor.
Returns
Product as ByteSize.

◆ operator*() [2/4]

template<Type::Integral T>
Size StormByte::operator* ( Size lhs,
T rhs )
constexprnoexcept

Mixed product.

Template Parameters
TIntegral type.
Parameters
lhsLeft factor.
rhsRight factor.
Returns
Product as Size.

◆ operator*() [3/4]

template<Type::Integral T>
ByteSize StormByte::operator* ( T lhs,
ByteSize rhs )
constexprnoexcept

Mixed product.

Template Parameters
TIntegral type.
Parameters
lhsLeft factor.
rhsRight factor.
Returns
Product as ByteSize.

◆ operator*() [4/4]

template<Type::Integral T>
Size StormByte::operator* ( T lhs,
Size rhs )
constexprnoexcept

Mixed product.

Template Parameters
TIntegral type.
Parameters
lhsLeft factor.
rhsRight factor.
Returns
Product as Size.

◆ operator+() [1/4]

template<Type::Integral T>
ByteSize StormByte::operator+ ( ByteSize lhs,
T rhs )
constexprnoexcept

Mixed sum.

Template Parameters
TIntegral type.
Parameters
lhsLeft addend.
rhsRight addend.
Returns
Sum as ByteSize.

◆ operator+() [2/4]

template<Type::Integral T>
Size StormByte::operator+ ( Size lhs,
T rhs )
constexprnoexcept

Mixed sum.

Template Parameters
TIntegral type.
Parameters
lhsLeft addend.
rhsRight addend.
Returns
Sum as Size.

◆ operator+() [3/4]

template<Type::Integral T>
ByteSize StormByte::operator+ ( T lhs,
ByteSize rhs )
constexprnoexcept

Mixed sum.

Template Parameters
TIntegral type.
Parameters
lhsLeft addend.
rhsRight addend.
Returns
Sum as ByteSize.

◆ operator+() [4/4]

template<Type::Integral T>
Size StormByte::operator+ ( T lhs,
Size rhs )
constexprnoexcept

Mixed sum.

Template Parameters
TIntegral type.
Parameters
lhsLeft addend.
rhsRight addend.
Returns
Sum as Size.

◆ operator-() [1/4]

template<Type::Integral T>
ByteSize StormByte::operator- ( ByteSize lhs,
T rhs )
constexprnoexcept

Mixed difference.

Template Parameters
TIntegral type.
Parameters
lhsMinuend.
rhsSubtrahend.
Returns
Difference as ByteSize.

◆ operator-() [2/4]

template<Type::Integral T>
Size StormByte::operator- ( Size lhs,
T rhs )
constexprnoexcept

Mixed difference.

Template Parameters
TIntegral type.
Parameters
lhsMinuend.
rhsSubtrahend.
Returns
Difference as Size.

◆ operator-() [3/4]

template<Type::Integral T>
ByteSize StormByte::operator- ( T lhs,
ByteSize rhs )
constexprnoexcept

Mixed difference.

Template Parameters
TIntegral type.
Parameters
lhsMinuend.
rhsSubtrahend.
Returns
Difference as ByteSize.

◆ operator-() [4/4]

template<Type::Integral T>
Size StormByte::operator- ( T lhs,
Size rhs )
constexprnoexcept

Mixed difference.

Template Parameters
TIntegral type.
Parameters
lhsMinuend.
rhsSubtrahend.
Returns
Difference as Size.

◆ operator/() [1/3]

template<Type::Integral T>
ByteSize StormByte::operator/ ( ByteSize lhs,
T rhs )
constexprnoexcept

Mixed quotient.

Template Parameters
TIntegral type.
Parameters
lhsDividend.
rhsDivisor.
Returns
Quotient as ByteSize.

◆ operator/() [2/3]

template<Type::Integral T>
Size StormByte::operator/ ( Size lhs,
T rhs )
constexprnoexcept

Mixed quotient.

Template Parameters
TIntegral type.
Parameters
lhsDividend.
rhsDivisor.
Returns
Quotient as Size.

◆ operator/() [3/3]

template<Type::Integral T>
Size StormByte::operator/ ( T lhs,
Size rhs )
constexprnoexcept

Mixed quotient.

Template Parameters
TIntegral type.
Parameters
lhsDividend.
rhsDivisor.
Returns
Quotient as Size.

◆ operator<<() [1/2]

std::ostream & StormByte::operator<< ( std::ostream & stream,
ByteSize size )
inline

Writes the IEC human-readable length.

Parameters
streamDestination.
sizeLength.
Returns
stream.

◆ operator<<() [2/2]

std::ostream & StormByte::operator<< ( std::ostream & stream,
Size size )
inline

Writes the decimal count.

Parameters
streamDestination.
sizeCount.
Returns
stream.

◆ operator==() [1/4]

template<Type::Integral T>
bool StormByte::operator== ( ByteSize lhs,
T rhs )
constexprnoexcept

Mixed equality.

Mixed equality with an integer.

Template Parameters
TIntegral type.
Parameters
lhsLeft length.
rhsRight integer.
Returns
Whether the numeric values match.

◆ operator==() [2/4]

template<Type::Integral T>
bool StormByte::operator== ( Size lhs,
T rhs )
constexprnoexcept

Mixed equality.

Template Parameters
TIntegral type.
Parameters
lhsLeft count.
rhsRight integer.
Returns
Whether the numeric values match.

◆ operator==() [3/4]

template<Type::Integral T>
bool StormByte::operator== ( T lhs,
ByteSize rhs )
constexprnoexcept

Mixed equality.

Mixed equality with an integer.

Template Parameters
TIntegral type.
Parameters
lhsLeft integer.
rhsRight length.
Returns
Whether the numeric values match.

◆ operator==() [4/4]

template<Type::Integral T>
bool StormByte::operator== ( T lhs,
Size rhs )
constexprnoexcept

Mixed equality.

Template Parameters
TIntegral type.
Parameters
lhsLeft integer.
rhsRight count.
Returns
Whether the numeric values match.

◆ Unexpected() [1/5]

template<typename E, typename... Args>
auto StormByte::Unexpected ( const std::string & fmt,
Args &&... args )

Builds std::unexpected from a format string and E(string).

Template Parameters
EError type. Constructed as E(formatted).
ArgsFormat argument types.
Parameters
fmtFormat string. Used as-is when Args is empty.
argsFormat arguments for std::vformat.
Returns
std::unexpected holding the error on Base's heap.

Formatting runs in the caller. E is then constructed on Base's heap, so Unexpected<VaultException>("Password '{}' not found", name) stays valid.

◆ Unexpected() [2/5]

template<typename Base, typename Derived>
requires Type::DerivedFrom<std::decay_t<Derived>, Base> && (!Type::SameAs<Base, std::decay_t<Derived>>)
auto StormByte::Unexpected ( Derived && error) ->std::unexpected< Safe::Shared< Base > >

Builds std::unexpected from a derived error.

Template Parameters
BaseError base type stored in the pointer.
DerivedConcrete error type, derived from Base and not the same type.
Parameters
errorDerived instance to own.
Returns
std::unexpected with an upcast Safe::Shared. The deleter still destroys Derived.

◆ Unexpected() [3/5]

template<typename E>
requires ( !requires { typename std::remove_cvref_t<E>::element_type; } || !Type::SameAs<std::remove_cvref_t<E>, Safe::Shared<typename std::remove_cvref_t<E>::element_type>> )
auto StormByte::Unexpected ( E && error)

Builds std::unexpected by constructing E.

Template Parameters
EError type.
Parameters
errorError instance, moved or copied onto Base's heap.
Returns
std::unexpected holding Safe::Shared of decay_t<E>.

◆ Unexpected() [4/5]

template<typename E>
auto StormByte::Unexpected ( Safe::Shared< E > error)

Forwards an error already stored by Expected.

Template Parameters
EError type.
Parameters
errorPointer previously built by Unexpected. Not reallocated.
Returns
std::unexpected holding that Safe::Shared.

◆ Unexpected() [5/5]

template<typename E>
auto StormByte::Unexpected ( std::shared_ptr< E > )
delete

Rejects a std::shared_ptr.

It is not on Base's heap, and Safe::Shared does not adopt it.

Template Parameters
EError type.

Variable Documentation

◆ B

ByteSize StormByte::B {1ull}
inlineconstexpr

One octet.

◆ EB

ByteSize StormByte::EB {1000ull * 1000 * 1000 * 1000 * 1000 * 1000}
inlineconstexpr

10^18 octets.

◆ EiB

ByteSize StormByte::EiB {1024ull * 1024 * 1024 * 1024 * 1024 * 1024}
inlineconstexpr

2^60 octets.

◆ GB

ByteSize StormByte::GB {1000ull * 1000 * 1000}
inlineconstexpr

10^9 octets.

◆ GiB

ByteSize StormByte::GiB {1024ull * 1024 * 1024}
inlineconstexpr

2^30 octets.

◆ KB

ByteSize StormByte::KB {1000ull}
inlineconstexpr

10^3 octets.

◆ KiB

ByteSize StormByte::KiB {1024ull}
inlineconstexpr

2^10 octets.

1 * KiB is 1024.

◆ MB

ByteSize StormByte::MB {1000ull * 1000}
inlineconstexpr

10^6 octets.

◆ MiB

ByteSize StormByte::MiB {1024ull * 1024}
inlineconstexpr

2^20 octets.

◆ PB

ByteSize StormByte::PB {1000ull * 1000 * 1000 * 1000 * 1000}
inlineconstexpr

10^15 octets.

◆ PiB

ByteSize StormByte::PiB {1024ull * 1024 * 1024 * 1024 * 1024}
inlineconstexpr

2^50 octets.

◆ TB

ByteSize StormByte::TB {1000ull * 1000 * 1000 * 1000}
inlineconstexpr

10^12 octets.

◆ TiB

ByteSize StormByte::TiB {1024ull * 1024 * 1024 * 1024}
inlineconstexpr

2^40 octets.