frequency.hpp

Go to the documentation of this file.

#pragma once
 
#include <cmath>
#include <compare>
#include <concepts>
#include <cstdint>
#include <cstdlib>
#include <limits>
#include <ratio>
#include <string>
#ifndef CONFIG_FREQUENCY_STD_FORMAT
#if __has_include(<format>) && defined(__cpp_lib_format)
#define CONFIG_FREQUENCY_STD_FORMAT 1
#else
#define CONFIG_FREQUENCY_STD_FORMAT 0
#endif
#endif
 
#if CONFIG_FREQUENCY_STD_FORMAT
#include <format>
#endif
#include <assert.h>
 
namespace freq {
 
template<typename Rep, typename Precision = std::ratio<1>>
class frequency;
 
template<typename T>
struct is_frequency : std::false_type {};
 
template<typename Rep, typename Precision>
struct is_frequency<frequency<Rep, Precision>> : std::true_type {};
 
template<typename T>
inline constexpr bool is_frequency_v = is_frequency<T>::value;
 
template<typename T, template<typename...> class Template>
struct _is_specialization_of : std::false_type {};
 
template<template<typename...> class Template, typename... Args>
struct _is_specialization_of<Template<Args...>, Template> : std::true_type {};
 
template<typename T, template<typename...> class Template>
inline constexpr bool _is_specialization_of_v = _is_specialization_of<T, Template>::value;
 
template<typename Rep>
concept not_frequency = !_is_specialization_of_v<Rep, frequency>;
 
template<typename T>
concept duration_like = requires(T t) {
    { t.count() };
    typename T::period;
    typename T::rep;
};
 
template<typename T>
concept distance_like = requires(T t) {
    { t.count() };
    typename T::period;
    typename T::rep;
};
 
template<typename Rep>
struct frequency_values {
    static constexpr Rep zero() noexcept { return Rep(0); }
 
    static constexpr Rep max() noexcept { return std::numeric_limits<Rep>::max(); }
 
    static constexpr Rep min() noexcept { return std::numeric_limits<Rep>::lowest(); }
};
 
template<typename T>
struct _is_ratio : std::false_type {};
 
template<std::intmax_t Num, std::intmax_t Denom>
struct _is_ratio<std::ratio<Num, Denom>> : std::true_type {};
 
template<typename T>
struct treat_as_inexact : std::bool_constant<std::floating_point<T>> {};
 
template<typename T>
inline constexpr bool treat_as_inexact_v = treat_as_inexact<T>::value;
 
consteval intmax_t _gcd(intmax_t m, intmax_t n) noexcept {
    while (n != 0) {
        intmax_t rem = m % n;
        m = n;
        n = rem;
    }
    return m;
}
 
// Runtime GCD for integer types (using Euclidean algorithm)
template<typename T>
constexpr T _runtime_gcd(T m, T n) noexcept {
    if (m < 0) {
        m = -m;
    }
    if (n < 0) {
        n = -n;
    }
    while (n != 0) {
        T rem = m % n;
        m = n;
        n = rem;
    }
    return m;
}
 
template<typename R1, typename R2>
inline constexpr intmax_t _safe_ratio_divide_den = [] {
    constexpr intmax_t g1 = _gcd(R1::num, R2::num);
    constexpr intmax_t g2 = _gcd(R1::den, R2::den);
    return (R1::den / g2) * (R2::num / g1);
}();
 
template<typename From, typename To>
concept _harmonic_precision = _safe_ratio_divide_den<From, To> == 1;
template<typename Rep, typename Precision>
class frequency {
    static_assert(!is_frequency<Rep>::value, "rep cannot be a frequency::frequency");
    static_assert(_is_ratio<Precision>::value, "precision must be a specialization of std::ratio");
    static_assert(Precision::num > 0, "precision must be positive");
 
public:
    using rep = Rep;
    using precision = typename Precision::type;
 
    constexpr frequency() = default;
    frequency(const frequency&) = default;
 
    template<typename Rep2>
        requires std::convertible_to<const Rep2&, rep> && (treat_as_inexact_v<rep> || !treat_as_inexact_v<Rep2>)
    constexpr explicit frequency(const Rep2& r)
        : _r(static_cast<rep>(r)) {}
 
    template<typename Rep2, typename Precision2>
        requires std::convertible_to<const Rep2&, rep> &&
        (treat_as_inexact_v<rep> || (_harmonic_precision<Precision2, precision> && !treat_as_inexact_v<Rep2>))
    constexpr frequency(const frequency<Rep2, Precision2>& f)
        : _r(frequency_cast<frequency>(f).count()) {}
 
    template<typename Rep2, typename Precision2>
        requires(!std::is_same_v<frequency, frequency<Rep2, Precision2>>) && (!treat_as_inexact_v<rep>) &&
        (!_harmonic_precision<Precision2, precision>)
    constexpr explicit frequency(const frequency<Rep2, Precision2>& f)
        : _r(frequency_cast<frequency>(f).count()) {}
 
    ~frequency() = default;
    frequency& operator=(const frequency&) = default;
 
    constexpr rep count() const { return _r; }
 
    constexpr frequency<typename std::common_type<rep>::type, precision> operator+() const {
        return frequency<typename std::common_type<rep>::type, precision>(_r);
    }
 
    constexpr frequency<typename std::common_type<rep>::type, precision> operator-() const {
        return frequency<typename std::common_type<rep>::type, precision>(-_r);
    }
 
    constexpr frequency& operator++() {
        ++_r;
        return *this;
    }
 
    constexpr frequency operator++(int) { return frequency(_r++); }
 
    constexpr frequency& operator--() {
        --_r;
        return *this;
    }
 
    constexpr frequency operator--(int) { return frequency(_r--); }
 
    constexpr frequency& operator+=(const frequency& f) {
        _r += f.count();
        return *this;
    }
 
    constexpr frequency& operator-=(const frequency& f) {
        _r -= f.count();
        return *this;
    }
 
    constexpr frequency& operator*=(const rep& r) {
        _r *= r;
        return *this;
    }
 
    constexpr frequency& operator/=(const rep& r) {
        _r /= r;
        return *this;
    }
 
    constexpr frequency& operator%=(const rep& r)
        requires(!treat_as_inexact_v<rep>)
    {
        _r %= r;
        return *this;
    }
 
    constexpr frequency& operator%=(const frequency& f)
        requires(!treat_as_inexact_v<rep>)
    {
        _r %= f.count();
        return *this;
    }
 
    static constexpr frequency zero() noexcept { return frequency(frequency_values<rep>::zero()); }
 
    static constexpr frequency min() noexcept { return frequency(frequency_values<rep>::min()); }
 
    static constexpr frequency max() noexcept { return frequency(frequency_values<rep>::max()); }
 
    template<duration_like Duration>
    constexpr Duration period() const {
        // Period ratio is the inverse of frequency precision
        // For frequency<Rep, ratio<N,D>>, the period of 1 tick is ratio<D,N> seconds
        using period_ratio = std::ratio_divide<std::ratio<1>, precision>;
        using duration_period = typename Duration::period;
        using cf = std::ratio_divide<period_ratio, duration_period>;
        using duration_rep = typename Duration::rep;
 
        if (_r == rep(0)) {
            return Duration::max();
        }
 
        // Integer-only path when both types are integral
        if constexpr (std::is_integral_v<rep> && std::is_integral_v<duration_rep>) {
#ifdef __SIZEOF_INT128__
            using cr = std::common_type_t<duration_rep, rep, intmax_t>;
            using wider_t = std::conditional_t<std::is_signed_v<cr>, __int128, unsigned __int128>;
#else
            using wider_t = intmax_t;
#endif
 
            wider_t count = static_cast<wider_t>(_r);
 
            if constexpr (cf::den == 1 && cf::num == 1) {
                // period_ticks = 1 / freq_count (in the target duration units)
                return Duration(static_cast<duration_rep>(1 / count));
            } else if constexpr (cf::den == 1) {
                // period_ticks = num / freq_count
                // Use GCD: g = gcd(num, count), then (num/g) / (count/g)
                wider_t num = static_cast<wider_t>(cf::num);
                wider_t g = _runtime_gcd(num, count);
                wider_t reduced_num = num / g;
                wider_t reduced_count = count / g;
                return Duration(static_cast<duration_rep>(reduced_num / reduced_count));
            } else if constexpr (cf::num == 1) {
                // period_ticks = 1 / (freq_count * den)
                wider_t denom = count * static_cast<wider_t>(cf::den);
                return Duration(static_cast<duration_rep>(1 / denom));
            } else {
                // period_ticks = num / (freq_count * den)
                // Use GCD: g = gcd(num, count), then (num/g) / ((count/g) * den)
                wider_t num = static_cast<wider_t>(cf::num);
                wider_t g = _runtime_gcd(num, count);
                wider_t reduced_num = num / g;
                wider_t reduced_count = count / g;
                wider_t denom = reduced_count * static_cast<wider_t>(cf::den);
                return Duration(static_cast<duration_rep>(reduced_num / denom));
            }
        } else {
            // Floating-point path
            using cr = std::common_type_t<duration_rep, double>;
 
            if constexpr (cf::den == 1 && cf::num == 1) {
                return Duration(static_cast<duration_rep>(1.0 / static_cast<double>(_r)));
            } else if constexpr (cf::den == 1) {
                return Duration(static_cast<duration_rep>(static_cast<cr>(cf::num) / static_cast<double>(_r)));
            } else if constexpr (cf::num == 1) {
                return Duration(static_cast<duration_rep>(1.0 / (static_cast<double>(_r) * static_cast<cr>(cf::den))));
            } else {
                return Duration(
                    static_cast<duration_rep>(
                        static_cast<cr>(cf::num) / (static_cast<double>(_r) * static_cast<cr>(cf::den))
                    )
                );
            }
        }
    }
 
    constexpr frequency harmonic(unsigned int n) const { return *this * n; }
 
    constexpr frequency subharmonic(unsigned int n) const {
        assert(n > 0 && "subharmonic divisor must be positive");
        return *this / n;
    }
 
    template<typename T = double>
    frequency octave_shift(T octaves) const {
        double multiplier = std::pow(2.0, static_cast<double>(octaves));
        if constexpr (std::is_integral_v<rep>) {
            return frequency(static_cast<rep>(std::round(static_cast<double>(_r) * multiplier)));
        } else {
            return frequency(static_cast<rep>(static_cast<double>(_r) * multiplier));
        }
    }
 
    template<typename T = double>
    frequency semitone_shift(T semitones) const {
        double multiplier = std::pow(2.0, static_cast<double>(semitones) / 12.0);
        if constexpr (std::is_integral_v<rep>) {
            return frequency(static_cast<rep>(std::round(static_cast<double>(_r) * multiplier)));
        } else {
            return frequency(static_cast<rep>(static_cast<double>(_r) * multiplier));
        }
    }
 
    template<typename T = double>
    T octaves_from(const frequency& other) const {
        return static_cast<T>(std::log2(static_cast<double>(_r) / static_cast<double>(other._r)));
    }
 
    template<typename T = double>
    T semitones_from(const frequency& other) const {
        return static_cast<T>(12.0 * std::log2(static_cast<double>(_r) / static_cast<double>(other._r)));
    }
 
    template<distance_like Distance, duration_like Duration>
    constexpr Distance wavelength(const Duration& time_per_unit_distance) const {
        // Get the period of this frequency
        using period_rep = double;
        using period_ratio = std::ratio_divide<std::ratio<1>, precision>;
 
        if (_r == rep(0)) {
            return Distance::max();
        }
 
        // Calculate period in our internal representation (1/frequency)
        period_rep wave_period = 1.0 / static_cast<double>(_r);
 
        // Convert to common time representation
        using duration_period = typename Duration::period;
        using time_cf = std::ratio_divide<period_ratio, duration_period>;
        using time_cr = std::common_type_t<period_rep, typename Duration::rep, double>;
 
        // Calculate period in time_per_unit_distance units
        time_cr period_in_duration_units;
        if constexpr (time_cf::den == 1 && time_cf::num == 1) {
            period_in_duration_units = static_cast<time_cr>(wave_period);
        } else if constexpr (time_cf::den == 1) {
            period_in_duration_units = static_cast<time_cr>(wave_period) * static_cast<time_cr>(time_cf::num);
        } else if constexpr (time_cf::num == 1) {
            period_in_duration_units = static_cast<time_cr>(wave_period) / static_cast<time_cr>(time_cf::den);
        } else {
            period_in_duration_units = static_cast<time_cr>(wave_period) * static_cast<time_cr>(time_cf::num) /
                static_cast<time_cr>(time_cf::den);
        }
 
        // Wavelength = period / time_per_unit_distance
        double wavelength_count = period_in_duration_units / static_cast<double>(time_per_unit_distance.count());
 
        return Distance(static_cast<typename Distance::rep>(wavelength_count));
    }
 
    template<distance_like Distance>
    constexpr Distance wavelength(double velocity = 299792458.0) const {
        if (_r == rep(0)) {
            return Distance::max();
        }
 
        // Convert frequency to Hz
        double freq_hz =
            static_cast<double>(_r) * static_cast<double>(precision::num) / static_cast<double>(precision::den);
 
        // Calculate wavelength in meters: wavelength = velocity / frequency
        double wavelength_meters = velocity / freq_hz;
 
        // Convert from meters to the target distance type's units
        // Distance::period represents the ratio of the distance unit to meters
        using distance_period = typename Distance::period;
        double wavelength_in_units =
            wavelength_meters * static_cast<double>(distance_period::den) / static_cast<double>(distance_period::num);
 
        return Distance(static_cast<typename Distance::rep>(wavelength_in_units));
    }
 
private:
    rep _r{};
};
 
template<typename ToFreq, typename Rep, typename Precision>
constexpr ToFreq frequency_cast(const frequency<Rep, Precision>& f) {
    if constexpr (std::is_same_v<ToFreq, frequency<Rep, Precision>>) {
        return f;
    } else {
        using to_rep = typename ToFreq::rep;
        using to_precision = typename ToFreq::precision;
        using cf = std::ratio_divide<Precision, to_precision>;
 
        // Use wider intermediate type for integer-to-integer conversions
        if constexpr (std::is_integral_v<Rep> && std::is_integral_v<to_rep>) {
#ifdef __SIZEOF_INT128__
            using cr = std::common_type_t<to_rep, Rep, intmax_t>;
            using wider_t = std::conditional_t<std::is_signed_v<cr>, __int128, unsigned __int128>;
#else
            using wider_t = intmax_t;
#endif
 
            if constexpr (cf::den == 1 && cf::num == 1) {
                return ToFreq(static_cast<to_rep>(f.count()));
            } else if constexpr (cf::den == 1) {
                wider_t result = static_cast<wider_t>(f.count()) * static_cast<wider_t>(cf::num);
                return ToFreq(static_cast<to_rep>(result));
            } else if constexpr (cf::num == 1) {
                wider_t result = static_cast<wider_t>(f.count()) / static_cast<wider_t>(cf::den);
                return ToFreq(static_cast<to_rep>(result));
            } else {
                // Use GCD to reduce operands: count * num / den
                // Compute g = gcd(count, den), then (count/g) * num / (den/g)
                wider_t count = static_cast<wider_t>(f.count());
                wider_t den = static_cast<wider_t>(cf::den);
                wider_t g = _runtime_gcd(count, den);
                wider_t reduced_count = count / g;
                wider_t reduced_den = den / g;
                wider_t result = reduced_count * static_cast<wider_t>(cf::num) / reduced_den;
                return ToFreq(static_cast<to_rep>(result));
            }
        } else {
            // Floating-point path
            using cr = std::common_type_t<to_rep, Rep, intmax_t>;
            if constexpr (cf::den == 1 && cf::num == 1) {
                return ToFreq(static_cast<to_rep>(f.count()));
            } else if constexpr (cf::den == 1) {
                return ToFreq(static_cast<to_rep>(static_cast<cr>(f.count()) * static_cast<cr>(cf::num)));
            } else if constexpr (cf::num == 1) {
                return ToFreq(static_cast<to_rep>(static_cast<cr>(f.count()) / static_cast<cr>(cf::den)));
            } else {
                return ToFreq(
                    static_cast<to_rep>(
                        static_cast<cr>(f.count()) * static_cast<cr>(cf::num) / static_cast<cr>(cf::den)
                    )
                );
            }
        }
    }
}
 
template<typename ToFreq, typename Rep, typename Precision>
constexpr ToFreq floor(const frequency<Rep, Precision>& f) {
    using to_rep = typename ToFreq::rep;
    ToFreq result = frequency_cast<ToFreq>(f);
 
    if constexpr (std::is_integral_v<Rep> && std::is_integral_v<to_rep>) {
        if (result > f) {
            return ToFreq(result.count() - to_rep(1));
        }
    }
 
    return result;
}
 
template<typename ToFreq, typename Rep, typename Precision>
constexpr ToFreq ceil(const frequency<Rep, Precision>& f) {
    using to_rep = typename ToFreq::rep;
    ToFreq result = frequency_cast<ToFreq>(f);
 
    if constexpr (std::is_integral_v<Rep> && std::is_integral_v<to_rep>) {
        if (result < f) {
            return ToFreq(result.count() + to_rep(1));
        }
    }
 
    return result;
}
 
template<typename ToFreq, typename Rep, typename Precision>
constexpr ToFreq round(const frequency<Rep, Precision>& f) {
    using to_rep = typename ToFreq::rep;
 
    if constexpr (std::is_integral_v<Rep> && std::is_integral_v<to_rep>) {
        ToFreq result = frequency_cast<ToFreq>(f);
        ToFreq lower = floor<ToFreq>(f);
        ToFreq upper = lower + ToFreq(to_rep(1));
 
        auto diff_lower = f - lower;
        auto diff_upper = upper - f;
 
        if (diff_lower < diff_upper) {
            return lower;
        } else if (diff_lower > diff_upper) {
            return upper;
        } else {
            // Tie: round to even
            return (lower.count() % to_rep(2) == to_rep(0)) ? lower : upper;
        }
    } else {
        return frequency_cast<ToFreq>(f);
    }
}
 
template<typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr auto beat(const frequency<Rep1, Precision1>& f1, const frequency<Rep2, Precision2>& f2)
    -> std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>> {
    using cf = std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>;
    return abs(cf(f1) - cf(f2));
}
 
template<typename Rep, typename Precision>
constexpr frequency<Rep, Precision> abs(const frequency<Rep, Precision>& f) {
    return f >= frequency<Rep, Precision>::zero() ? f : -f;
}
 
template<typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr auto operator+(const frequency<Rep1, Precision1>& lhs, const frequency<Rep2, Precision2>& rhs)
    -> std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>> {
    using cf = std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>;
    return cf(cf(lhs).count() + cf(rhs).count());
}
 
template<typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr auto operator-(const frequency<Rep1, Precision1>& lhs, const frequency<Rep2, Precision2>& rhs)
    -> std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>> {
    using cf = std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>;
    return cf(cf(lhs).count() - cf(rhs).count());
}
 
template<typename Rep1, typename Precision, typename Rep2>
    requires not_frequency<Rep2> && std::convertible_to<const Rep2&, std::common_type_t<Rep1, Rep2>>
constexpr auto operator*(const frequency<Rep1, Precision>& f, const Rep2& r)
    -> frequency<std::common_type_t<Rep1, Rep2>, Precision> {
    using cf = frequency<std::common_type_t<Rep1, Rep2>, Precision>;
    return cf(cf(f).count() * r);
}
 
template<typename Rep1, typename Rep2, typename Precision>
    requires not_frequency<Rep1> && std::convertible_to<const Rep1&, std::common_type_t<Rep1, Rep2>>
constexpr auto operator*(const Rep1& r, const frequency<Rep2, Precision>& f)
    -> frequency<std::common_type_t<Rep1, Rep2>, Precision> {
    return f * r;
}
 
template<typename Rep1, typename Precision, typename Rep2>
    requires not_frequency<Rep2> && std::convertible_to<const Rep2&, std::common_type_t<Rep1, Rep2>>
constexpr auto operator/(const frequency<Rep1, Precision>& f, const Rep2& s)
    -> frequency<std::common_type_t<Rep1, Rep2>, Precision> {
    using cf = frequency<std::common_type_t<Rep1, Rep2>, Precision>;
    return cf(cf(f).count() / s);
}
 
template<typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr auto operator/(const frequency<Rep1, Precision1>& lhs, const frequency<Rep2, Precision2>& rhs)
    -> std::common_type_t<Rep1, Rep2> {
    using cf = std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>;
    return cf(lhs).count() / cf(rhs).count();
}
 
template<typename Rep1, typename Precision, typename Rep2>
    requires not_frequency<Rep2> && std::convertible_to<const Rep2&, std::common_type_t<Rep1, Rep2>> &&
    (!treat_as_inexact_v<Rep1> && !treat_as_inexact_v<Rep2>)
constexpr auto operator%(const frequency<Rep1, Precision>& f, const Rep2& s)
    -> frequency<std::common_type_t<Rep1, Rep2>, Precision> {
    using cf = frequency<std::common_type_t<Rep1, Rep2>, Precision>;
    return cf(cf(f).count() % s);
}
 
template<typename Rep1, typename Precision1, typename Rep2, typename Precision2>
    requires(!treat_as_inexact_v<Rep1> && !treat_as_inexact_v<Rep2>)
constexpr auto operator%(const frequency<Rep1, Precision1>& lhs, const frequency<Rep2, Precision2>& rhs)
    -> std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>> {
    using cf = std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>;
    return cf(cf(lhs).count() % cf(rhs).count());
}
 
template<typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr bool operator==(const frequency<Rep1, Precision1>& lhs, const frequency<Rep2, Precision2>& rhs) {
    using ct = std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>;
    return ct(lhs).count() == ct(rhs).count();
}
 
template<typename Rep1, typename Precision1, typename Rep2, typename Precision2>
    requires std::three_way_comparable<std::common_type_t<Rep1, Rep2>>
constexpr auto operator<=>(const frequency<Rep1, Precision1>& lhs, const frequency<Rep2, Precision2>& rhs) {
    using ct = std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>;
    return ct(lhs).count() <=> ct(rhs).count();
}
 
using millihertz = frequency<int64_t, std::milli>;
using hertz = frequency<int64_t>;
using kilohertz = frequency<int64_t, std::kilo>;
using megahertz = frequency<int64_t, std::mega>;
using gigahertz = frequency<int64_t, std::giga>;
using terahertz = frequency<int64_t, std::tera>;
 
 
// SI prefix for a hertz-per-count ratio; nullptr when unmapped.
template<typename Ratio>
struct _si_prefix {
    static constexpr const char* value = nullptr;
};
template<>
struct _si_prefix<std::femto> {
    static constexpr const char* value = "f";
};
template<>
struct _si_prefix<std::pico> {
    static constexpr const char* value = "p";
};
template<>
struct _si_prefix<std::nano> {
    static constexpr const char* value = "n";
};
template<>
struct _si_prefix<std::micro> {
    static constexpr const char* value = "µ";
};
template<>
struct _si_prefix<std::milli> {
    static constexpr const char* value = "m";
};
template<>
struct _si_prefix<std::ratio<1>> {
    static constexpr const char* value = "";
};
template<>
struct _si_prefix<std::kilo> {
    static constexpr const char* value = "k";
};
template<>
struct _si_prefix<std::mega> {
    static constexpr const char* value = "M";
};
template<>
struct _si_prefix<std::giga> {
    static constexpr const char* value = "G";
};
template<>
struct _si_prefix<std::tera> {
    static constexpr const char* value = "T";
};
template<typename Ratio>
inline constexpr const char* _si_prefix_v = _si_prefix<typename Ratio::type>::value;
 
// Appends a NUL-terminated string to a format output iterator.
template<typename OutputIt>
constexpr OutputIt _format_append(OutputIt out, const char* s) {
    for (; *s != '\0'; ++s) {
        *out++ = *s;
    }
    return out;
}
 
#if CONFIG_FREQUENCY_STD_FORMAT
// Reports an unusable format spec from a formatter's parse().
//
// std::format constant-evaluates parse() to check the format string, so
// throwing there makes a bad spec a compile error rather than a runtime fault.
// Where exceptions are unavailable, calling a non-constexpr function fails that
// same constant evaluation and so reports the error at compile time too; a
// runtime parse (std::vformat with a runtime format string) has no way to
// report it and terminates.
[[noreturn]] inline void _format_error(const char* what) {
#if defined(__cpp_exceptions) && __cpp_exceptions
    throw std::format_error(what);
#else
    (void)what;
    std::abort();
#endif
}
#endif
template<typename Rep, typename Precision>
    requires(!treat_as_inexact_v<Rep>)
std::string to_string(const frequency<Rep, Precision>& f) {
    using precision = typename frequency<Rep, Precision>::precision;
    static_assert(_si_prefix_v<precision> != nullptr, "frequency: precision has no SI prefix");
    return std::to_string(f.count()) + _si_prefix_v<precision> + "Hz";
}
 
} // namespace freq
 
namespace std {
 
template<typename Rep1, typename Precision1, typename Rep2, typename Precision2>
struct common_type<freq::frequency<Rep1, Precision1>, freq::frequency<Rep2, Precision2>> {
private:
    using common_precision = std::ratio<
        freq::_gcd(Precision1::num, Precision2::num),
        (Precision1::den / freq::_gcd(Precision1::den, Precision2::den)) * Precision2::den>;
 
public:
    using type = freq::frequency<std::common_type_t<Rep1, Rep2>, common_precision>;
};
 
#if CONFIG_FREQUENCY_STD_FORMAT
// "{}" prints the exact stored count with a precision-qualified unit
// (kilohertz(433) -> "433kHz"). A non-empty spec is applied to the value in
// hertz (as double): std::format("{:.1f}", millihertz(1500)) == "1.5Hz".
template<typename Rep, typename Precision>
struct formatter<freq::frequency<Rep, Precision>> {
private:
    using _precision = typename freq::frequency<Rep, Precision>::precision;
    static constexpr const char* _prefix = freq::_si_prefix_v<_precision>;
    std::formatter<double> _num;
    bool _has_spec = false;
 
public:
    constexpr auto parse(format_parse_context& ctx) {
        auto it = ctx.begin();
        if (it == ctx.end() || *it == '}') {
            if constexpr (_prefix == nullptr) {
                freq::_format_error("frequency: precision has no SI prefix; use an explicit format spec");
            }
            return it;
        }
        _has_spec = true;
        return _num.parse(ctx);
    }
 
    template<typename FormatContext>
    auto format(const freq::frequency<Rep, Precision>& f, FormatContext& ctx) const {
        if (_has_spec) {
            double hz = static_cast<double>(f.count()) * _precision::num / _precision::den;
            auto out = _num.format(hz, ctx);
            return freq::_format_append(out, "Hz");
        }
        auto out = std::format_to(ctx.out(), "{}", f.count());
        out = freq::_format_append(out, _prefix);
        return freq::_format_append(out, "Hz");
    }
};
#endif
 
} // namespace std
 
namespace frequency_literals {
namespace detail {
 
template<unsigned long long Value, unsigned long long Power>
struct pow10 {
    static constexpr unsigned long long value = 10 * pow10<Value, Power - 1>::value;
};
 
template<unsigned long long Value>
struct pow10<Value, 0> {
    static constexpr unsigned long long value = Value;
};
 
template<char... Digits>
struct parse_int;
 
template<char D, char... Rest>
struct parse_int<D, Rest...> {
    static_assert(D >= '0' && D <= '9', "invalid digit");
    static constexpr unsigned long long value = pow10<D - '0', sizeof...(Rest)>::value + parse_int<Rest...>::value;
};
 
template<char D>
struct parse_int<D> {
    static_assert(D >= '0' && D <= '9', "invalid digit");
    static constexpr unsigned long long value = D - '0';
};
 
template<typename Freq, char... Digits>
constexpr Freq check_overflow() {
    using parsed = parse_int<Digits...>;
    constexpr typename Freq::rep repval = parsed::value;
    static_assert(
        repval >= 0 && static_cast<unsigned long long>(repval) == parsed::value,
        "literal value cannot be represented by frequency type"
    );
    return Freq(repval);
}
 
} // namespace detail
template<char... Digits>
constexpr freq::millihertz operator""_mHz() {
    return detail::check_overflow<freq::millihertz, Digits...>();
}
 
template<char... Digits>
constexpr freq::hertz operator""_Hz() {
    return detail::check_overflow<freq::hertz, Digits...>();
}
 
template<char... Digits>
constexpr freq::kilohertz operator""_kHz() {
    return detail::check_overflow<freq::kilohertz, Digits...>();
}
 
template<char... Digits>
constexpr freq::megahertz operator""_MHz() {
    return detail::check_overflow<freq::megahertz, Digits...>();
}
 
template<char... Digits>
constexpr freq::gigahertz operator""_GHz() {
    return detail::check_overflow<freq::gigahertz, Digits...>();
}
 
template<char... Digits>
constexpr freq::terahertz operator""_THz() {
    return detail::check_overflow<freq::terahertz, Digits...>();
}
 
} // namespace frequency_literals