Core Library Utilities#

group utility

This module contains basic core library utilities, such as an ergonomic way to silence unused argument warnings and comparison functions that eliminate the pitfalls associated with comparing signed and unsigned types and/or floating point numbers.

Functions

template<typename ...Args>
constexpr auto ignore([[maybe_unused]] Args&&... args) noexcept -> void#

Utility function to ignore the given values.

Example#

auto my_func(i32 arg1, i32 arg2, i32 arg3) -> void {
    // TODO: Implement this!
    // eliminate unused argument warnings/errors during compilation
    ignore(arg1, arg2, arg3);
}

Template Parameters:

Args – - The types of the things to ignore

Parameters:

args – - The things to ignore

group comparison

Hyperion provides safe comparison functions for safely comparing any types providing comparison operators, including floating point types, as well as mixed comparisons between signed, unsigned, and floating point types.

Example#

using hyperion::operator""_f32;
const auto my_f32 = 12'345.6789_f32;
const auto my_other_f32 = 11'345.6789_f32;
const auto is_equal = hyperion::equality_compare(my_f32, my_other_f32);

Enums

enum class EpsilonType : bool#

Types of epsilons usable in floating point comparisons, either Absolute, i.e. a fixed magnitude difference, or Relative, i.e. a percentage magnitude difference.

Example#

static constexpr auto my_epsilon = make_epsilon<EpsilonType::Relative>{0.1_f64};

Values:

enumerator Absolute#
enumerator Relative#

Functions

template<EpsilonType TType, Arithmetic TEpsilon>
constexpr auto make_epsilon(TEpsilon &&epsilon) -> Epsilon<TType, TEpsilon>#

Returns an Epsilon of the specified EpsilonType and given value.

Example#

static constexpr auto my_epsilon = make_epsilon<EpsilonType::Relative>{0.1_f64};

Template Parameters:
  • TType – The EpsilonType of the epsilon

  • TEpsilon – The arithmetic type of the epsilon (e.g., f64, or int)

Parameters:

epsilon – the arithmetic value of the epsilon (e.g. 0.001_f64)

Returns:

The Epsilon

template<typename TLhs, typename TRhs, EpsilonKind TEpsilon = decltype(detail::make_epsilon<TLhs, TRhs>())> requires constexpr EqualityComparable< TLhs, TRhs > auto equality_compare (TLhs &&lhs, TRhs &&rhs, TEpsilon epsilon=detail::make_epsilon< TLhs, TRhs >()) noexcept(noexcept(lhs==rhs) &&noexcept(rhs==lhs)) -> bool

Safely compares lhs and rhs for equality, taking into account signedness differences and accounting for floating point inaccuracies with an Epsilon

Example#

constexpr auto my_epsilon = Epsilon<EpsilonType::Relative>{0.1_f64};

auto value1 = getSomeValue(1);
auto value2 = getSomeValue(2);
// check that value1 and value2 are within 10% of whichever is largest
auto is_equal = equality_compare(value1, value2, my_epsilon);

Template Parameters:
  • TLhs – The type of the left-hand argument in the comparison

  • TRhs – The type of the right-hand argument in the comparison Defaults to an Absolute epsilon of type fmax.

Parameters:
  • lhs – The left-hand argument in the comparison

  • rhs – The right-hand argument in the comparison

  • epsilon – The Epsilon used for floating point comparison. Defaults to an Absolute epsilon equal to the machine epsilon corresponding with the type that is the wider of the two types TLhs and TRhs.

Returns:

Whether lhs and rhs are equal

template<typename TLhs, typename TRhs, EpsilonKind TEpsilon = decltype(detail::make_epsilon<TLhs, TRhs>())> requires constexpr InequalityComparable< TLhs, TRhs > auto inequality_compare (TLhs &&lhs, TRhs &&rhs, TEpsilon epsilon=detail::make_epsilon< TLhs, TRhs >()) noexcept(noexcept(lhs==rhs) &&noexcept(rhs==lhs)) -> bool

Safely compares lhs and rhs for inequality, taking into account signedness differences and accounting for floating point inaccuracies with an Epsilon

Example#

constexpr auto my_epsilon = Epsilon<EpsilonType::Relative>{0.1_f64};

auto value1 = getSomeValue(1);
auto value2 = getSomeValue(2);
// check that value1 and value2 are _not_ within 10% of whichever is largest
auto is_equal = inequality_compare(value1, value2, my_epsilon);

Template Parameters:
  • TLhs – The type of the left-hand argument in the comparison

  • TRhs – The type of the right-hand argument in the comparison Defaults to an Absolute epsilon of type fmax.

Parameters:
  • lhs – The left-hand argument in the comparison

  • rhs – The right-hand argument in the comparison

  • epsilon – The Epsilon used for floating point comparison. Defaults to an Absolute epsilon equal to the machine epsilon corresponding with the type that is the wider of the two types TLhs and TRhs.

Returns:

Whether lhs and rhs are not equal

template<typename TLhs, typename TRhs, EpsilonKind TEpsilon = decltype(detail::make_epsilon<TLhs, TRhs>())> requires constexpr LessThanComparable< TLhs, TRhs > auto less_than_compare (TLhs &&lhs, TRhs &&rhs, TEpsilon epsilon=detail::make_epsilon< TLhs, TRhs >()) noexcept(noexcept(lhs==rhs) &&noexcept(rhs==lhs)) -> bool

Safely compares whether lhs is less than rhs, taking into account signedness differences and accounting for floating point inaccuracies with an Epsilon

Example#

constexpr auto my_epsilon = Epsilon<EpsilonType::Relative>{0.1_f64};

auto value1 = getSomeValue(1);
auto value2 = getSomeValue(2);
// check that value1 is less than value2 by at least 10%
auto is_equal = less_than_compare(value1, value2, my_epsilon);

Template Parameters:
  • TLhs – The type of the left-hand argument in the comparison

  • TRhs – The type of the right-hand argument in the comparison Defaults to an Absolute epsilon of type fmax.

Parameters:
  • lhs – The left-hand argument in the comparison

  • rhs – The right-hand argument in the comparison

  • epsilon – The Epsilon used for floating point comparison. Defaults to an Absolute epsilon equal to the machine epsilon corresponding with the type that is the wider of the two types TLhs and TRhs.

Returns:

Whether lhs is less than rhs

template<typename TLhs, typename TRhs, EpsilonKind TEpsilon = decltype(detail::make_epsilon<TLhs, TRhs>())> requires constexpr LessThanOrEqualComparable< TLhs, TRhs > auto less_than_or_equal_compare (TLhs &&lhs, TRhs &&rhs, TEpsilon epsilon=detail::make_epsilon< TLhs, TRhs >()) noexcept(noexcept(lhs==rhs) &&noexcept(rhs==lhs)) -> bool

Safely compares whether lhs is less than or equal to rhs, taking into account signedness differences and accounting for floating point inaccuracies with an Epsilon

Example#

constexpr auto my_epsilon = Epsilon<EpsilonType::Relative>{0.1_f64};

auto value1 = getSomeValue(1);
auto value2 = getSomeValue(2);
// check that value1 is less than value2 by at least 10%,
// or that value1 and value2 are within 10% of whichever is largest
auto is_equal = less_than_or_equal_compare(value1, value2, my_epsilon);

Template Parameters:
  • TLhs – The type of the left-hand argument in the comparison

  • TRhs – The type of the right-hand argument in the comparison Defaults to an Absolute epsilon of type fmax.

Parameters:
  • lhs – The left-hand argument in the comparison

  • rhs – The right-hand argument in the comparison

  • epsilon – The Epsilon used for floating point comparison. Defaults to an Absolute epsilon equal to the machine epsilon corresponding with the type that is the wider of the two types TLhs and TRhs.

Returns:

Whether lhs is less than or equal to rhs

template<typename TLhs, typename TRhs, EpsilonKind TEpsilon = decltype(detail::make_epsilon<TLhs, TRhs>())> requires constexpr LessThanComparable< TLhs, TRhs > auto greater_than_compare (TLhs &&lhs, TRhs &&rhs, TEpsilon epsilon=detail::make_epsilon< TLhs, TRhs >()) noexcept(noexcept(lhs==rhs) &&noexcept(rhs==lhs)) -> bool

Safely compares whether lhs is greater than rhs, taking into account signedness differences and accounting for floating point inaccuracies with an Epsilon

Example#

constexpr auto my_epsilon = Epsilon<EpsilonType::Relative>{0.1_f64};

auto value1 = getSomeValue(1);
auto value2 = getSomeValue(2);
// check that value1 is greater than value2 by at least 10%
auto is_equal = greater_than_compare(value1, value2, my_epsilon);

Template Parameters:
  • TLhs – The type of the left-hand argument in the comparison

  • TRhs – The type of the right-hand argument in the comparison Defaults to an Absolute epsilon of type fmax.

Parameters:
  • lhs – The left-hand argument in the comparison

  • rhs – The right-hand argument in the comparison

  • epsilon – The Epsilon used for floating point comparison. Defaults to an Absolute epsilon equal to the machine epsilon corresponding with the type that is the wider of the two types TLhs and TRhs.

Returns:

Whether lhs is greater than rhs

template<typename TLhs, typename TRhs, EpsilonKind TEpsilon = decltype(detail::make_epsilon<TLhs, TRhs>())> requires constexpr LessThanOrEqualComparable< TLhs, TRhs > auto greater_than_or_equal_compare (TLhs &&lhs, TRhs &&rhs, TEpsilon epsilon=detail::make_epsilon< TLhs, TRhs >()) noexcept(noexcept(lhs==rhs) &&noexcept(rhs==lhs)) -> bool

Safely compares whether lhs is greater than or equal to rhs, taking into account signedness differences and accounting for floating point inaccuracies with an Epsilon

Example#

constexpr auto my_epsilon = Epsilon<EpsilonType::Relative>{0.1_f64};

auto value1 = getSomeValue(1);
auto value2 = getSomeValue(2);
// check that value1 is greater than value2 by at least 10%,
// or that value1 and value2 are within 10% of whichever is largest
auto is_equal = less_than_or_equal_compare(value1, value2, my_epsilon);

Template Parameters:
  • TLhs – The type of the left-hand argument in the comparison

  • TRhs – The type of the right-hand argument in the comparison Defaults to an Absolute epsilon of type fmax.

Parameters:
  • lhs – The left-hand argument in the comparison

  • rhs – The right-hand argument in the comparison

  • epsilon – The Epsilon used for floating point comparison. Defaults to an Absolute epsilon equal to the machine epsilon corresponding with the type that is the wider of the two types TLhs and TRhs.

Returns:

Whether lhs is greater than or equal to rhs

Variables

template<typename TLhs, typename TRhs> concept EqualityComparable  = requires(const TLhs& lhs, const TRhs& rhs) {lhs == rhs;rhs == lhs;}

Concept definition requiring that a TLhs is equality comparable with a TRhs

template<typename TLhs, typename TRhs> concept InequalityComparable  = requires(const TLhs& lhs, const TRhs& rhs) {lhs != rhs;rhs != lhs;}

Concept definition requiring that a TLhs is inequality comparable with a TRhs

template<typename TLhs, typename TRhs> concept LessThanComparable   = requires(const TLhs& lhs, const TRhs& rhs) { lhs < rhs; }

Concept definition requiring that a TLhs is less-than comparable with a TRhs

template<typename TLhs, typename TRhs> concept LessThanOrEqualComparable   = requires(const TLhs& lhs, const TRhs& rhs) { lhs <= rhs; }

Concept definition requiring that a TLhs is less-than-or-equal comparable with a TRhs

template<typename TLhs, typename TRhs> concept GreaterThanComparable   = requires(const TLhs& lhs, const TRhs& rhs) { lhs > rhs; }

Concept definition requiring that a TLhs is greater-than comparable with a TRhs

template<typename TLhs, typename TRhs> concept GreaterThanOrEqualComparable   = requires(const TLhs& lhs, const TRhs& rhs) { lhs >= rhs; }

Concept definition requiring that a TLhs is greater-than-or-equal comparable with a TRhs

template<typename TType> concept Arithmetic  = std::is_arithmetic_v<std::remove_cvref_t<TType>>&& !(std::same_as<std::remove_cvref_t<TType>, bool>|| std::same_as<std::remove_cvref_t<TType>, char>|| std::same_as<std::remove_cvref_t<TType>, char8_t>|| std::same_as<std::remove_cvref_t<TType>, char16_t>|| std::same_as<std::remove_cvref_t<TType>, char32_t>)

Concept definition requiring that a type is truly arithmetic (a non-character, non-boolean integer type or floating point type)

template<typename TType>
static constexpr auto is_epsilon_specialization_v = is_epsilon_specialization<TType>::value#

Value of the type trait is_epsilon_specialization. Used to check whether TType is a specialization of Epsilon

Template Parameters:

TType – The type to check

template<typename TType> concept EpsilonKind   = is_epsilon_specialization_v<std::remove_cvref_t<TType>>

Concept requiring that TType is a specialization of Epsilon

template<EpsilonType TType = EpsilonType::Absolute, Arithmetic TNumeric = fmax>
class Epsilon#
#include <hyperion/platform/compare.h>

Represents an Absolute or Relative epsilon of a specific Arithmetic type.

Example#

static constexpr auto my_epsilon = make_epsilon<EpsilonType::Relative>{0.1_f64};

Template Parameters:
  • TType – The EpsilonType this Epsilon represents

  • TNumeric – The Arithmetic type of this Epsilon

Public Functions

inline explicit(false) const expr Epsilon(TNumeric val)#

Constructs an Epsilon with the given numeric value.

Parameters:

val – The numeric value of this Epsilon

inline constexpr auto epsilon(const Arithmetic auto &lhs, const Arithmetic auto &rhs) const noexcept -> TNumeric#

Returns the Absolute epsilon this Epsilon would represent when used in a comparison between the two arguments.

Parameters:
  • lhs – The left-hand argument of the theoretical comparsion

  • rhs – The right-hand argument of the theoretical comparsion

Returns:

The Absolute epsilon this Epsilon represents when used in a comparision between lhs and rhs

inline constexpr auto value() const noexcept -> TNumeric#

Returns the numeric value of this Epsilon

Returns:

The value of the Epsilon

template<typename TType>
struct is_epsilon_specialization : public std::false_type#
#include <hyperion/platform/compare.h>

Type trait to check whether TType is a specialization of Epsilon

Template Parameters:

TType – The type to check

Warning

doxygenconcept: Cannot find concept “hyperion::platform::compare::EqualityComparable” in doxygen xml output for project “hyperion::platform” from directory: _build/xml

Warning

doxygenconcept: Cannot find concept “hyperion::platform::compare::InequalityComparable” in doxygen xml output for project “hyperion::platform” from directory: _build/xml

Warning

doxygenconcept: Cannot find concept “hyperion::platform::compare::LessThanComparable” in doxygen xml output for project “hyperion::platform” from directory: _build/xml

Warning

doxygenconcept: Cannot find concept “hyperion::platform::compare::LessThanOrEqualComparable” in doxygen xml output for project “hyperion::platform” from directory: _build/xml

Warning

doxygenconcept: Cannot find concept “hyperion::platform::compare::GreaterThanComparable” in doxygen xml output for project “hyperion::platform” from directory: _build/xml

Warning

doxygenconcept: Cannot find concept “hyperion::platform::compare::GreaterThanOrEqualComparable” in doxygen xml output for project “hyperion::platform” from directory: _build/xml

Warning

doxygenconcept: Cannot find concept “hyperion::platform::compare::ThreeWayComparable” in doxygen xml output for project “hyperion::platform” from directory: _build/xml

Warning

doxygenconcept: Cannot find concept “hyperion::platform::compare::Arithmetic” in doxygen xml output for project “hyperion::platform” from directory: _build/xml

Warning

doxygenconcept: Cannot find concept “hyperion::platform::compare::EpsilonKind” in doxygen xml output for project “hyperion::platform” from directory: _build/xml