Core Library Utilities#

group Utilities

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(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 Safe Comparison Functions

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>())>
constexpr 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>())>
constexpr 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>())>
constexpr 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>())>
constexpr 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>())>
constexpr 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>())>
constexpr 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 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<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

template<typename TLhs, typename TRhs>
concept EqualityComparable#
#include <hyperion/platform/compare.h>

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

template<typename TLhs, typename TRhs>
concept InequalityComparable#
#include <hyperion/platform/compare.h>

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

template<typename TLhs, typename TRhs>
concept LessThanComparable#
#include <hyperion/platform/compare.h>

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

template<typename TLhs, typename TRhs>
concept LessThanOrEqualComparable#
#include <hyperion/platform/compare.h>

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

template<typename TLhs, typename TRhs>
concept GreaterThanComparable#
#include <hyperion/platform/compare.h>

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

template<typename TLhs, typename TRhs>
concept GreaterThanOrEqualComparable#
#include <hyperion/platform/compare.h>

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

Warning

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

template<typename TType>
concept Arithmetic#
#include <hyperion/platform/compare.h>

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

template<typename TType>
concept EpsilonKind#
#include <hyperion/platform/compare.h>

Concept requiring that TType is a specialization of Epsilon