utility.h File Reference

Declarations for utility functions. More...

#include <algorithm>
#include <condition_variable>
#include <memory>
#include <mutex>
#include <optional>
#include <ostream>
#include <string>
#include <string_view>
#include <type_traits>
#include <variant>
#include <vector>

Include dependency graph for utility.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	util::__either< false, X, Y >
	Type selector that chooses the second type when the condition is false. More...
struct	util::__either< true, X, Y >
	Type selector that chooses the first type when the condition is true. More...
struct	util::__false_v< T, std::enable_if_t< instantiation_of_v< std::optional, T > > >
	Helper specialization for optional values. More...
struct	util::__false_v< T, std::enable_if_t< is_pointer_v< T > > >
	Enables an overload only when the provided type is a pointer. More...
struct	util::__false_v< T, std::enable_if_t< std::is_same_v< T, bool > > >
	Type trait comparing a value with a boolean template argument. More...
struct	util::__instantiation_of< X, Y >
struct	util::__instantiation_of< X, X< Y... > >
struct	argument_type< T(U)>
	Extracts the argument type from a single-argument function signature. More...
class	util::buffer_t< T >
	Owning contiguous buffer with an explicit logical element count. More...
struct	util::Destroy< T, ReturnType, function >
	Deleter adapter that destroys the wrapped pointer. More...
class	util::Either< X, Y >
	Tagged storage for one of two possible value types. More...
struct	util::endian::endian_helper< T, S >
struct	util::endian::endian_helper< T, std::enable_if_t< instantiation_of_v< std::optional, T > > >
	Helper specialization for optional values. More...
struct	util::endian::endian_helper< T, std::enable_if_t<!(instantiation_of_v< std::optional, T >)> >
	Helper specialization for optional values. More...
struct	util::endian::endianness< T >
	Describes the byte order used when serializing values. More...
class	util::FailGuard< T >
	Scope guard that runs a cleanup action unless it is disabled. More...
struct	util::Function< ReturnType, Args >
	Callable wrapper used by utility metaprogramming helpers. More...
class	util::hash< T >
	Hash functor that hashes the raw bytes of trivially-copyable values. More...
class	util::Hex< T >
	Formatter that exposes a value's bytes as hexadecimal text. More...
struct	util::overloaded< Ts >
struct	util::point_t
	Two-dimensional integer point. More...
class	util::uniq_ptr< T, D >
	Unique pointer wrapper with customizable pointer and deleter types. More...
class	util::wrap_ptr< T >
	Pointer wrapper that may borrow or own the pointee. More...

Macros
#define	KITTY_DECL_CONSTR(x)
	Declare the standard move operations and out-of-line default constructor for a type.
#define	KITTY_DEFAULT_CONSTR(x)
	Declare defaulted copy and move operations for a value type.
#define	KITTY_DEFAULT_CONSTR_MOVE(x)
	Declare defaulted noexcept move construction and assignment for a type.
#define	KITTY_DEFAULT_CONSTR_MOVE_THROW(x)
	Declare defaulted move construction and assignment that may throw.
#define	KITTY_USING_MOVE_T(move_t, t, init_val, z)
	Define a move-only RAII wrapper with caller-provided initial value and destructor body.
#define	KITTY_WHILE_LOOP(x, y, z)
	Execute an initializer followed by a while loop body without leaking helper names.
#define	TUPLE_2D(a, b, expr)
	Evaluate an expression returning a 2-tuple and bind both elements to local references.
#define	TUPLE_2D_REF(a, b, expr)
	Bind both elements of an existing 2-tuple expression to local references.
#define	TUPLE_3D(a, b, c, expr)
	Evaluate an expression returning a 3-tuple and bind all elements to local references.
#define	TUPLE_3D_REF(a, b, c, expr)
	Bind all elements of an existing 3-tuple expression to local references.
#define	TUPLE_EL(a, b, expr)
	Evaluate a tuple expression and bind one selected element to a local reference.
#define	TUPLE_EL_REF(a, b, expr)
	Bind one selected element of an existing tuple expression to a local reference.

Typedefs
template<class T >
using	util::c_ptr = safe_ptr<T, c_free<T>>
	Safe pointer wrapper for memory released by std::free.
template<class T , void(**)(T *) function>
using	util::dyn_safe_ptr = safe_ptr<T, dynamic<T, void, function>>
	Unique pointer using a runtime-provided destroy function.
template<class T , class ReturnType , ReturnType(**)(T *) function>
using	util::dyn_safe_ptr_v2 = safe_ptr<T, dynamic<T, ReturnType, function>>
	Safe pointer wrapper for runtime-resolved release functions with status returns.
template<bool V, class X , class Y >
using	util::either_t = typename __either<V, X, Y>::type
	Compile-time selector for one of two types.
template<class T >
using	util::optional_t
	Optional trait value used by endian serialization helpers.
template<class T , typename Function< void, T * >::type function>
using	util::safe_ptr = uniq_ptr<T, Destroy<T *, void, function>>
	Unique pointer using a compile-time C-style destroy function.
template<class T , class ReturnType , typename Function< ReturnType, T * >::type function>
using	util::safe_ptr_v2 = uniq_ptr<T, Destroy<T *, ReturnType, function>>
	Safe pointer wrapper for APIs whose release function returns a status value.
template<class P >
using	util::shared_t = std::shared_ptr<typename P::element_type>
	Shared pointer type matching a safe pointer wrapper's element type.

Functions
template<class T >
void	util::append_struct (std::vector< uint8_t > &buf, const T &_struct)
	Append the raw bytes of a trivially-copyable structure to a byte buffer.
template<class T >
auto	util::endian::big (T x)
	Convert a value to or from big-endian byte order.
template<class T >
void	util::c_free (T *p)
	Release memory allocated by C APIs with free.
template<class T , class ReturnType , ReturnType(**)(T *) function>
void	util::dynamic (T *p)
	Create a non-owning dynamic buffer view over contiguous memory.
template<class T >
T	util::either (std::optional< T > &&l, T &&r)
	Build an either value from a left-hand value.
template<class T >
auto	util::enm (const T &val) -> const std::underlying_type_t< T > &
	Convert between enum values and their string names.
template<class T >
auto	util::enm (T &val) -> std::underlying_type_t< T > &
	Convert between enum values and their string names.
template<class T >
auto	util::fail_guard (T &&f)
	Create a scope guard that runs unless it is disabled.
std::int64_t	util::from_chars (const char *begin, const char *end)
	Convert from chars.
template<class T >
T	util::from_hex (const std::string_view &hex, bool rev=false)
	Convert from hex.
std::string	util::from_hex_vec (const std::string &hex, bool rev=false)
	Convert from hex vec.
std::int64_t	util::from_view (const std::string_view &number)
	Convert from view.
template<class T >
Hex< T >	util::hex (const T &elem, bool rev=false)
	Serialize an element as hexadecimal text.
template<class C >
std::string	util::hex_vec (C &&c, bool rev=false)
	Parse hexadecimal text into a byte vector.
template<class It >
std::string	util::hex_vec (It begin, It end, bool rev=false)
	Convert a value to a vector of hexadecimal bytes.
template<class T >
auto	util::endian::little (T x)
	Convert a value to or from little-endian byte order.
template<typename T >
std::string	util::log_hex (const T &value)
	Format a value as hexadecimal text for logging.
template<class P , class T >
shared_t< P >	util::make_shared (T *pointer)
	Create a shared object or message.
template<class T1 , class D1 , class T2 , class D2 >
bool	util::operator!= (const std::unique_ptr< T1, D1 > &x, const uniq_ptr< T2, D2 > &y)
	Compare a standard unique pointer with a Sunshine unique pointer.
template<class T , class D >
bool	util::operator!= (const uniq_ptr< T, D > &x, std::nullptr_t)
	Compare a Sunshine unique pointer with null.
template<class T1 , class D1 , class T2 , class D2 >
bool	util::operator!= (const uniq_ptr< T1, D1 > &x, const std::unique_ptr< T1, D1 > &y)
	Compare a Sunshine unique pointer with a standard unique pointer.
template<class T1 , class D1 , class T2 , class D2 >
bool	util::operator!= (const uniq_ptr< T1, D1 > &x, const uniq_ptr< T2, D2 > &y)
	Compare two Sunshine unique pointers by their stored addresses.
template<class T , class D >
bool	util::operator!= (std::nullptr_t, const uniq_ptr< T, D > &y)
	Compare null with a Sunshine unique pointer.
template<class T1 , class D1 , class T2 , class D2 >
bool	util::operator== (const std::unique_ptr< T1, D1 > &x, const uniq_ptr< T2, D2 > &y)
	Compare a standard unique pointer with a Sunshine unique pointer.
template<class T , class D >
bool	util::operator== (const uniq_ptr< T, D > &x, std::nullptr_t)
	Compare a Sunshine unique pointer with null.
template<class T1 , class D1 , class T2 , class D2 >
bool	util::operator== (const uniq_ptr< T1, D1 > &x, const std::unique_ptr< T1, D1 > &y)
	Compare a Sunshine unique pointer with a standard unique pointer.
template<class T1 , class D1 , class T2 , class D2 >
bool	util::operator== (const uniq_ptr< T1, D1 > &x, const uniq_ptr< T2, D2 > &y)
	Compare two Sunshine unique pointers by their stored addresses.
template<class T , class D >
bool	util::operator== (std::nullptr_t, const uniq_ptr< T, D > &y)
	Compare null with a Sunshine unique pointer.
template<class... Ts>
	util::overloaded (Ts...) -> overloaded< Ts... >
	Combine multiple callables into one overload set for std::visit.
template<class T >
std::string_view	util::view (const T &data)
	Read the current value without removing it from the queue.
template<class It >
std::string_view	util::view (It begin, It end)
	Read the current value without removing it from the queue.

Variables
template<class T >
constexpr bool	util::is_pointer_v
	Trait value indicating whether the template argument is a pointer.

Detailed Description

Declarations for utility functions.

Macro Definition Documentation

KITTY_DECL_CONSTR

#define KITTY_DECL_CONSTR

(

x

)

Value:

 
 \
  x(x &&) noexcept = default; \
 \
  x &operator=(x &&) noexcept = default; \
 \
  x();

Declare the standard move operations and out-of-line default constructor for a type.

KITTY_DEFAULT_CONSTR

#define KITTY_DEFAULT_CONSTR

(

x

)

Value:

  KITTY_DEFAULT_CONSTR_MOVE(x) \
 \
  x(const x &) noexcept = default; \
 \
  x &operator=(const x &) = default;

Declare defaulted copy and move operations for a value type.

KITTY_DEFAULT_CONSTR_MOVE

#define KITTY_DEFAULT_CONSTR_MOVE

(

x

)

Value:

 
 \
  x(x &&) noexcept = default; \
 \
  x &operator=(x &&) noexcept = default;

Declare defaulted noexcept move construction and assignment for a type.

KITTY_DEFAULT_CONSTR_MOVE_THROW

#define KITTY_DEFAULT_CONSTR_MOVE_THROW

(

x

)

Value:

 
 \
  x(x &&) = default; \
 \
  x &operator=(x &&) = default; \
 \
  x() = default;

Declare defaulted move construction and assignment that may throw.

KITTY_WHILE_LOOP

#define KITTY_WHILE_LOOP	(		x,
			y,
			z )

Value:

  { \
    x; \
    while (y) z \
  }

Execute an initializer followed by a while loop body without leaking helper names.

TUPLE_2D

#define TUPLE_2D	(		a,
			b,
			expr )

Value:

  decltype(expr) a##_##b = expr; \
  auto &a = std::get<0>(a##_##b); \
  auto &b = std::get<1>(a##_##b)

Evaluate an expression returning a 2-tuple and bind both elements to local references.

TUPLE_2D_REF

#define TUPLE_2D_REF	(		a,
			b,
			expr )

Value:

  auto &a##_##b = expr; \
  auto &a = std::get<0>(a##_##b); \
  auto &b = std::get<1>(a##_##b)

Bind both elements of an existing 2-tuple expression to local references.

TUPLE_3D

#define TUPLE_3D	(		a,
			b,
			c,
			expr )

Value:

  decltype(expr) a##_##b##_##c = expr; \
  auto &a = std::get<0>(a##_##b##_##c); \
  auto &b = std::get<1>(a##_##b##_##c); \
  auto &c = std::get<2>(a##_##b##_##c)

Evaluate an expression returning a 3-tuple and bind all elements to local references.

TUPLE_3D_REF

#define TUPLE_3D_REF	(		a,
			b,
			c,
			expr )

Value:

  auto &a##_##b##_##c = expr; \
  auto &a = std::get<0>(a##_##b##_##c); \
  auto &b = std::get<1>(a##_##b##_##c); \
  auto &c = std::get<2>(a##_##b##_##c)

Bind all elements of an existing 3-tuple expression to local references.

TUPLE_EL

#define TUPLE_EL	(		a,
			b,
			expr )

Value:

  decltype(expr) a##_ = expr; \
  auto &a = std::get<b>(a##_)

Evaluate a tuple expression and bind one selected element to a local reference.

TUPLE_EL_REF

#define TUPLE_EL_REF	(		a,
			b,
			expr )

Value:

  auto &a = std::get<b>(expr)

Bind one selected element of an existing tuple expression to a local reference.

Typedef Documentation

optional_t

template<class T >

using util::optional_t

Initial value:

 either_t<
    (std::is_same_v<T, bool> || is_pointer_v<T>),
    T,
    std::optional<T>>

Optional trait value used by endian serialization helpers.

Function Documentation

append_struct()

template<class T >

void util::append_struct	(	std::vector< uint8_t > &	buf,
		const T &	_struct )

Append the raw bytes of a trivially-copyable structure to a byte buffer.

Parameters

buf	Destination buffer used for protocol serialization.
_struct	Structure instance whose in-memory bytes should be appended.

big()

template<class T >

auto util::endian::big ( T x )

inline

Convert a value to or from big-endian byte order.

Parameters

x	Value or pointer to convert.

Returns

Input represented in big-endian byte order.

c_free()

template<class T >

void util::c_free

(

T *

p

)

Release memory allocated by C APIs with free.

Parameters

p	Pointer passed to the deleter or conversion helper.

dynamic()

template<class T , class ReturnType , ReturnType(**)(T *) function>

void util::dynamic

(

T *

p

)

Create a non-owning dynamic buffer view over contiguous memory.

Parameters

p	Pointer passed to the deleter or conversion helper.

either()

template<class T >

T util::either	(	std::optional< T > &&	l,
		T &&	r )

Build an either value from a left-hand value.

Parameters

l	Left-hand value used to construct the either object.
r	Fallback value returned when the optional left-hand value is empty.

Returns

Left-hand optional value when present, otherwise the fallback.

enm() [1/2]

template<class T >

auto util::enm

(

const T &

val

)

-> const std::underlying_type_t<T> &

Convert between enum values and their string names.

Parameters

val	Value assigned to the synchronized object.

Returns

Const reference to the enum's underlying integral storage.

enm() [2/2]

template<class T >

auto util::enm

(

T &

val

)

-> std::underlying_type_t<T> &

Convert between enum values and their string names.

Parameters

val	Value assigned to the synchronized object.

Returns

Mutable reference to the enum's underlying integral storage.

fail_guard()

template<class T >

auto util::fail_guard ( T && f )

nodiscard

Create a scope guard that runs unless it is disabled.

Parameters

f	Callable executed by the helper.

Returns

Fail guard object that invokes the callable on scope exit.

from_chars()

std::int64_t util::from_chars ( const char * begin, const char * end )

inline

Convert from chars.

Parameters

begin	Iterator or pointer marking the start of the input range.
end	Iterator or pointer marking the end of the input range.

Returns

Value converted from chars.

from_hex()

template<class T >

T util::from_hex	(	const std::string_view &	hex,
		bool	rev = false )

Convert from hex.

Parameters

hex	Hexadecimal text to decode.
rev	Whether bytes should be emitted in reverse order.

Returns

Value converted from hex.

from_hex_vec()

std::string util::from_hex_vec ( const std::string & hex, bool rev = false )

inline

Convert from hex vec.

Parameters

hex	Hexadecimal text to decode.
rev	Whether bytes should be emitted in reverse order.

Returns

Value converted from hex vec.

from_view()

std::int64_t util::from_view ( const std::string_view & number )

inline

Convert from view.

Parameters

number

Integer value to serialize or convert.

Returns

Value converted from view.

hex()

template<class T >

Hex< T > util::hex	(	const T &	elem,
		bool	rev = false )

Serialize an element as hexadecimal text.

Parameters

elem	Element value being serialized as bytes.
rev	Whether bytes should be emitted in reverse order.

Returns

Lightweight hexadecimal formatter for the input object.

hex_vec() [1/2]

template<class C >

std::string util::hex_vec	(	C &&	c,
		bool	rev = false )

Parse hexadecimal text into a byte vector.

Parameters

c	Character or context value being converted or released.
rev	Whether bytes should be emitted in reverse order.

Returns

Hexadecimal string for the contiguous container.

hex_vec() [2/2]

template<class It >

std::string util::hex_vec	(	It	begin,
		It	end,
		bool	rev = false )

Convert a value to a vector of hexadecimal bytes.

Parameters

begin	Iterator or pointer marking the start of the input range.
end	Iterator or pointer marking the end of the input range.
rev	Whether bytes should be emitted in reverse order.

Returns

Hexadecimal string for the byte range.

little()

template<class T >

auto util::endian::little ( T x )

inline

Convert a value to or from little-endian byte order.

Parameters

x	Value or pointer to convert.

Returns

Input represented in little-endian byte order.

log_hex()

template<typename T >

std::string util::log_hex

(

const T &

value

)

Format a value as hexadecimal text for logging.

Parameters

value

Value whose bytes should be logged in hexadecimal.

Returns

Hexadecimal string representation of the input object.

make_shared()

template<class P , class T >

shared_t< P > util::make_shared

(

T *

pointer

)

Create a shared object or message.

Parameters

pointer

Raw pointer adopted by the safe pointer wrapper.

Returns

Constructed shared object.

operator!=() [1/5]

template<class T1 , class D1 , class T2 , class D2 >

bool util::operator!=	(	const std::unique_ptr< T1, D1 > &	x,
		const uniq_ptr< T2, D2 > &	y )

Compare a standard unique pointer with a Sunshine unique pointer.

Parameters

x	Left-hand pointer or value being compared.
y	Right-hand pointer or value being compared.

Returns

True when the wrappers store different pointer addresses.

operator!=() [2/5]

template<class T , class D >

bool util::operator!=	(	const uniq_ptr< T, D > &	x,
		std::nullptr_t	)

Compare a Sunshine unique pointer with null.

Parameters

x	Left-hand pointer or value being compared.

Returns

True when the wrapper owns a pointer.

operator!=() [3/5]

template<class T1 , class D1 , class T2 , class D2 >

bool util::operator!=	(	const uniq_ptr< T1, D1 > &	x,
		const std::unique_ptr< T1, D1 > &	y )

Compare a Sunshine unique pointer with a standard unique pointer.

Parameters

x	Left-hand pointer or value being compared.
y	Right-hand pointer or value being compared.

Returns

True when the wrappers store different pointer addresses.

operator!=() [4/5]

template<class T1 , class D1 , class T2 , class D2 >

bool util::operator!=	(	const uniq_ptr< T1, D1 > &	x,
		const uniq_ptr< T2, D2 > &	y )

Compare two Sunshine unique pointers by their stored addresses.

Parameters

x	Left-hand pointer or value being compared.
y	Right-hand pointer or value being compared.

Returns

True when the wrappers store different pointer addresses.

operator!=() [5/5]

template<class T , class D >

bool util::operator!=	(	std::nullptr_t	,
		const uniq_ptr< T, D > &	y )

Compare null with a Sunshine unique pointer.

Parameters

y	Right-hand pointer or value being compared.

Returns

True when the wrapper owns a pointer.

operator==() [1/5]

template<class T1 , class D1 , class T2 , class D2 >

bool util::operator==	(	const std::unique_ptr< T1, D1 > &	x,
		const uniq_ptr< T2, D2 > &	y )

Compare a standard unique pointer with a Sunshine unique pointer.

Parameters

x	Left-hand pointer or value being compared.
y	Right-hand pointer or value being compared.

Returns

True when both wrappers store the same pointer address.

operator==() [2/5]

template<class T , class D >

bool util::operator==	(	const uniq_ptr< T, D > &	x,
		std::nullptr_t	)

Compare a Sunshine unique pointer with null.

Parameters

x	Left-hand pointer or value being compared.

Returns

True when the wrapper does not own a pointer.

operator==() [3/5]

template<class T1 , class D1 , class T2 , class D2 >

bool util::operator==	(	const uniq_ptr< T1, D1 > &	x,
		const std::unique_ptr< T1, D1 > &	y )

Compare a Sunshine unique pointer with a standard unique pointer.

Parameters

x	Left-hand pointer or value being compared.
y	Right-hand pointer or value being compared.

Returns

True when both wrappers store the same pointer address.

operator==() [4/5]

template<class T1 , class D1 , class T2 , class D2 >

bool util::operator==	(	const uniq_ptr< T1, D1 > &	x,
		const uniq_ptr< T2, D2 > &	y )

Compare two Sunshine unique pointers by their stored addresses.

Parameters

x	Left-hand pointer or value being compared.
y	Right-hand pointer or value being compared.

Returns

True when both wrappers store the same pointer address.

operator==() [5/5]

template<class T , class D >

bool util::operator==	(	std::nullptr_t	,
		const uniq_ptr< T, D > &	y )

Compare null with a Sunshine unique pointer.

Parameters

y	Right-hand pointer or value being compared.

Returns

True when the wrapper does not own a pointer.

view() [1/2]

template<class T >

std::string_view util::view

(

const T &

data

)

Read the current value without removing it from the queue.

Parameters

data	Payload or state data to serialize, deserialize, or forward.

Returns

String view over the contiguous object's bytes.

view() [2/2]

template<class It >

std::string_view util::view	(	It	begin,
		It	end )

Read the current value without removing it from the queue.

Parameters

begin	Iterator or pointer marking the start of the input range.
end	Iterator or pointer marking the end of the input range.

Returns

String view spanning the iterator range.

Variable Documentation

is_pointer_v

template<class T >

bool util::is_pointer_v

constexpr

Initial value:

=
    instantiation_of_v<std::unique_ptr, T> ||
    instantiation_of_v<std::shared_ptr, T> ||
    instantiation_of_v<uniq_ptr, T> ||
    std::is_pointer_v<T>

Trait value indicating whether the template argument is a pointer.