decibel.hpp

Go to the documentation of this file.

#pragma once
 
#include <cassert>
#include <cmath>
#include <quanta/electro.hpp>
 
namespace quanta::electro {
 
// ============================================================================
// Gain: a dimensionless logarithmic ratio
// ============================================================================
 
struct decibel_unit {
    static constexpr const char* symbol = "dB";
};
 
template<typename Rep, typename Precision = std::ratio<1>>
using gain = quantity<decibel_unit, Rep, Precision>;
 
using decibels = gain<int64_t>;
using centidecibels = gain<int64_t, std::centi>;
using millidecibels = gain<int64_t, std::milli>;
 
// ============================================================================
// References
// ============================================================================
 
struct milliwatt_reference {
    using unit = watt_unit;
    using precision = std::milli;
    static constexpr int factor = 10;
    static constexpr const char* symbol = "dBm";
};
 
struct watt_reference {
    using unit = watt_unit;
    using precision = std::ratio<1>;
    static constexpr int factor = 10;
    static constexpr const char* symbol = "dBW";
};
 
struct volt_reference {
    using unit = volt_unit;
    using precision = std::ratio<1>;
    static constexpr int factor = 20;
    static constexpr const char* symbol = "dBV";
};
 
struct millivolt_reference {
    using unit = volt_unit;
    using precision = std::milli;
    static constexpr int factor = 20;
    static constexpr const char* symbol = "dBmV";
};
 
struct microvolt_reference {
    using unit = volt_unit;
    using precision = std::micro;
    static constexpr int factor = 20;
    static constexpr const char* symbol = "dBµV";
};
 
 
template<typename Reference>
concept decibel_reference = requires {
    typename Reference::unit;
    typename Reference::precision;
    { Reference::factor } -> std::convertible_to<int>;
    { Reference::symbol } -> std::convertible_to<const char*>;
} && (Reference::factor == 10 || Reference::factor == 20);
 
template<typename Reference>
inline constexpr bool is_power_reference_v = false;
 
template<decibel_reference Reference>
inline constexpr bool is_power_reference_v<Reference> = Reference::factor == 10;
 
template<typename Reference>
inline constexpr bool is_field_reference_v = false;
 
template<decibel_reference Reference>
inline constexpr bool is_field_reference_v<Reference> = Reference::factor == 20;
 
// ============================================================================
// level
// ============================================================================
 
template<typename Reference, typename Rep, typename Precision = std::ratio<1>>
class level;
 
template<typename T>
struct is_level : std::false_type {};
 
template<typename Reference, typename Rep, typename Precision>
struct is_level<level<Reference, Rep, Precision>> : std::true_type {};
 
template<typename T>
inline constexpr bool is_level_v = is_level<T>::value;
 
template<typename Reference, typename Rep, typename Precision>
class level {
    static_assert(decibel_reference<Reference>, "Reference must satisfy the decibel_reference concept");
 
public:
    using reference = Reference;
    using rep = Rep;
    using precision = typename Precision::type;
    using offset = gain<Rep, Precision>;
 
    constexpr level() = default;
    level(const level&) = default;
 
    template<typename Rep2>
        requires std::convertible_to<const Rep2&, rep> && (treat_as_inexact_v<rep> || !treat_as_inexact_v<Rep2>)
    constexpr explicit level(const Rep2& r)
        : _o(static_cast<rep>(r)) {}
 
    constexpr explicit level(const offset& o)
        : _o(o) {}
 
    template<typename Rep2, typename Precision2>
        requires std::convertible_to<gain<Rep2, Precision2>, offset>
    constexpr level(const level<Reference, Rep2, Precision2>& l)
        : _o(l.offset_from_reference()) {}
 
    template<typename Rep2, typename Precision2>
        requires(!std::is_same_v<level, level<Reference, Rep2, Precision2>>) &&
        (!std::convertible_to<gain<Rep2, Precision2>, offset>) &&
        std::constructible_from<offset, gain<Rep2, Precision2>>
    constexpr explicit level(const level<Reference, Rep2, Precision2>& l)
        : _o(offset(l.offset_from_reference())) {}
 
    ~level() = default;
    level& operator=(const level&) = default;
 
    constexpr offset offset_from_reference() const { return _o; }
 
    constexpr rep count() const { return _o.count(); }
 
    constexpr level operator-() const { return level(-_o); }
    constexpr level operator+() const { return *this; }
 
    constexpr level& operator+=(const offset& o) {
        _o += o;
        return *this;
    }
 
    constexpr level& operator-=(const offset& o) {
        _o -= o;
        return *this;
    }
 
    static constexpr level reference_level() noexcept { return level(offset::zero()); }
 
    static constexpr level min() noexcept { return level(offset::min()); }
 
    static constexpr level max() noexcept { return level(offset::max()); }
 
private:
    offset _o{};
};
 
template<typename ToLevel, typename Reference, typename Rep, typename Precision>
    requires(!std::is_same_v<typename ToLevel::reference, Reference>) ||
    detail::_quantity_cast_requirements<gain<Rep, Precision>, typename ToLevel::offset>
constexpr ToLevel level_cast(const level<Reference, Rep, Precision>& l) {
    // The constraint admits a cast between references, so that this reports it.
    static_assert(
        std::is_same_v<typename ToLevel::reference, Reference>, "level_cast cannot convert between different references"
    );
    return ToLevel(quantity_cast<typename ToLevel::offset>(l.offset_from_reference()));
}
 
template<typename ToLevel, typename Reference, typename Rep, typename Precision>
constexpr ToLevel floor(const level<Reference, Rep, Precision>& l) {
    static_assert(std::is_same_v<typename ToLevel::reference, Reference>, "floor cannot convert between references");
    return ToLevel(floor<typename ToLevel::offset>(l.offset_from_reference()));
}
 
template<typename ToLevel, typename Reference, typename Rep, typename Precision>
constexpr ToLevel ceil(const level<Reference, Rep, Precision>& l) {
    static_assert(std::is_same_v<typename ToLevel::reference, Reference>, "ceil cannot convert between references");
    return ToLevel(ceil<typename ToLevel::offset>(l.offset_from_reference()));
}
 
template<typename ToLevel, typename Reference, typename Rep, typename Precision>
constexpr ToLevel trunc(const level<Reference, Rep, Precision>& l) {
    static_assert(std::is_same_v<typename ToLevel::reference, Reference>, "trunc cannot convert between references");
    return ToLevel(trunc<typename ToLevel::offset>(l.offset_from_reference()));
}
 
template<typename ToLevel, typename Reference, typename Rep, typename Precision>
constexpr ToLevel round(const level<Reference, Rep, Precision>& l) {
    static_assert(std::is_same_v<typename ToLevel::reference, Reference>, "round cannot convert between references");
    return ToLevel(round<typename ToLevel::offset>(l.offset_from_reference()));
}
 
// ============================================================================
// Affine arithmetic: level +/- gain -> level, level - level -> gain
// ============================================================================
 
template<typename R1, typename P1, typename R2, typename P2>
using _common_gain = std::common_type_t<gain<R1, P1>, gain<R2, P2>>;
template<typename Reference, typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr auto
operator+(const level<Reference, Rep1, Precision1>& l, const quantity<decibel_unit, Rep2, Precision2>& g) {
    using cg = _common_gain<Rep1, Precision1, Rep2, Precision2>;
    using cl = level<Reference, typename cg::rep, typename cg::precision>;
    return cl(cg(l.offset_from_reference()) + cg(g));
}
 
template<typename Reference, typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr auto
operator+(const quantity<decibel_unit, Rep2, Precision2>& g, const level<Reference, Rep1, Precision1>& l) {
    return l + g;
}
 
template<typename Reference, typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr auto
operator-(const level<Reference, Rep1, Precision1>& l, const quantity<decibel_unit, Rep2, Precision2>& g) {
    using cg = _common_gain<Rep1, Precision1, Rep2, Precision2>;
    using cl = level<Reference, typename cg::rep, typename cg::precision>;
    return cl(cg(l.offset_from_reference()) - cg(g));
}
 
template<typename Reference, typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr auto operator-(const level<Reference, Rep1, Precision1>& a, const level<Reference, Rep2, Precision2>& b) {
    return a.offset_from_reference() - b.offset_from_reference();
}
 
template<typename Reference, typename Rep1, typename Precision1, typename Rep2, typename Precision2>
constexpr bool operator==(const level<Reference, Rep1, Precision1>& a, const level<Reference, Rep2, Precision2>& b) {
    return a.offset_from_reference() == b.offset_from_reference();
}
 
template<typename Reference, typename Rep1, typename Precision1, typename Rep2, typename Precision2>
    requires std::three_way_comparable<std::common_type_t<Rep1, Rep2>>
constexpr auto operator<=>(const level<Reference, Rep1, Precision1>& a, const level<Reference, Rep2, Precision2>& b) {
    return a.offset_from_reference() <=> b.offset_from_reference();
}
 
// ============================================================================
// Linear domain conversions (not constexpr before C++26)
// ============================================================================
 
template<typename Offset>
constexpr double _db_value(const Offset& o) {
    return quantity_cast<gain<double>>(o).count();
}
 
// The inverse of _db_value, rounding to nearest (ties to even, matching
// round<>) for integral reps. This exists because quantity_cast truncates when converting
// from an inexact rep, and truncation would round e.g. -73.5 dB the wrong way.
template<typename Offset>
inline Offset _db_offset(double db) {
    if constexpr (treat_as_inexact_v<typename Offset::rep>) {
        return quantity_cast<Offset>(gain<double>(db));
    } else {
        using p = typename Offset::precision;
        const double ticks = db * static_cast<double>(p::den) / static_cast<double>(p::num);
        double rounded = std::floor(ticks);
        const double frac = ticks - rounded;
        if (frac > 0.5 || (frac == 0.5 && std::fmod(rounded, 2.0) != 0.0)) {
            rounded += 1.0;
        }
        // Saturate rather than cast an out-of-range value (including an
        // infinity), which is undefined. min() is a power of two and so exact
        // as a double; max() converts exactly or rounds up to a power of two,
        // and in both cases every smaller double fits the rep.
        using rep = typename Offset::rep;
        if (rounded >= static_cast<double>(std::numeric_limits<rep>::max())) {
            return Offset(std::numeric_limits<rep>::max());
        }
        if (rounded <= static_cast<double>(std::numeric_limits<rep>::min())) {
            return Offset(std::numeric_limits<rep>::min());
        }
        return Offset(static_cast<rep>(rounded));
    }
}
template<typename Reference, typename Rep, typename Precision>
inline auto to_linear(const level<Reference, Rep, Precision>& l) {
    using linear = quantity<typename Reference::unit, double, typename Reference::precision>;
    return linear(std::pow(10.0, _db_value(l.offset_from_reference()) / Reference::factor));
}
 
template<typename ToLevel, typename Unit, typename Rep, typename Precision>
inline ToLevel to_level(const quantity<Unit, Rep, Precision>& q) {
    using ref = typename ToLevel::reference;
    static_assert(
        std::is_same_v<typename ref::unit, Unit>, "to_level: quantity unit does not match the level reference"
    );
 
    using linear = quantity<Unit, double, typename ref::precision>;
    const double ratio = quantity_cast<linear>(q).count();
    if (!(ratio > 0.0)) {
        if constexpr (std::floating_point<typename ToLevel::rep>) {
            if (std::isnan(ratio)) {
                return ToLevel(std::numeric_limits<typename ToLevel::rep>::quiet_NaN());
            }
            assert(ratio >= 0.0 && "to_level: quantity must be non-negative and not NaN");
            return ToLevel(-std::numeric_limits<typename ToLevel::rep>::infinity());
        } else {
            assert(ratio >= 0.0 && "to_level: quantity must be non-negative and not NaN");
            return ToLevel::min();
        }
    }
    return ToLevel(_db_offset<typename ToLevel::offset>(ref::factor * std::log10(ratio)));
}
 
template<typename Rep, typename Precision>
inline double power_ratio(const quantity<decibel_unit, Rep, Precision>& g) {
    return std::pow(10.0, _db_value(g) / 10.0);
}
 
template<typename Rep, typename Precision>
inline double amplitude_ratio(const quantity<decibel_unit, Rep, Precision>& g) {
    return std::pow(10.0, _db_value(g) / 20.0);
}
 
inline gain<double> power_gain(double ratio) {
    assert(ratio > 0.0 && "power_gain: ratio must be positive");
    return gain<double>(10.0 * std::log10(ratio));
}
 
inline gain<double> amplitude_gain(double ratio) {
    assert(ratio > 0.0 && "amplitude_gain: ratio must be positive");
    return gain<double>(20.0 * std::log10(ratio));
}
 
template<typename Reference, typename Rep1, typename Precision1, typename Rep2, typename Precision2>
    requires is_power_reference_v<Reference>
inline auto add_powers(const level<Reference, Rep1, Precision1>& a, const level<Reference, Rep2, Precision2>& b) {
    using cg = _common_gain<Rep1, Precision1, Rep2, Precision2>;
    using result = level<Reference, typename cg::rep, typename cg::precision>;
    return to_level<result>(to_linear(a) + to_linear(b));
}
 
// ============================================================================
// Type aliases
// ============================================================================
 
template<typename Rep, typename Precision = std::ratio<1>>
using dbm_level = level<milliwatt_reference, Rep, Precision>;
 
template<typename Rep, typename Precision = std::ratio<1>>
using dbw_level = level<watt_reference, Rep, Precision>;
 
template<typename Rep, typename Precision = std::ratio<1>>
using dbv_level = level<volt_reference, Rep, Precision>;
 
template<typename Rep, typename Precision = std::ratio<1>>
using dbmv_level = level<millivolt_reference, Rep, Precision>;
 
template<typename Rep, typename Precision = std::ratio<1>>
using dbuv_level = level<microvolt_reference, Rep, Precision>;
 
using dbm = dbm_level<int64_t>;
using centi_dbm = dbm_level<int64_t, std::centi>;
using dbw = dbw_level<int64_t>;
using dbv = dbv_level<int64_t>;
using dbmv = dbmv_level<int64_t>;
using dbuv = dbuv_level<int64_t>;
using centi_dbuv = dbuv_level<int64_t, std::centi>;
 
 
// ============================================================================
// String conversion and formatting
// ============================================================================
 
template<typename Precision>
struct quantity_suffix<decibel_unit, Precision> {};
 
// The number of decimal places needed to render a count at the given precision
// as a fixed-point decimal, or -1 when the precision is not 1, 1/10, 1/100, ...
consteval int _decimal_places(intmax_t num, intmax_t den) {
    if (num != 1) {
        return -1;
    }
    int places = 0;
    while (den % 10 == 0) {
        den /= 10;
        ++places;
    }
    return den == 1 ? places : -1;
}
 
template<typename Precision>
inline constexpr bool _is_decimal_precision = _decimal_places(Precision::num, Precision::den) >= 0;
 
// A count at the given precision, in decibels, as a double.
template<typename Precision, typename Rep>
constexpr double _db_double(const Rep& count) {
    return static_cast<double>(count) * Precision::num / Precision::den;
}
 
// A count at the given precision rendered without a format spec, in decibels.
// Integer counts are shown exactly with one decimal place per decade of
// precision ("10.50"); floating-point counts in the shortest fixed notation
// that round-trips (never scientific).
template<typename Precision, typename Rep>
inline std::string _format_db(const Rep& count) {
    static_assert(_is_decimal_precision<Precision>, "precision cannot be rendered as a fixed-point decimal");
    if constexpr (std::floating_point<Rep>) {
        Rep value = count;
        if constexpr (Precision::den != 1) {
            value /= static_cast<Rep>(Precision::den);
        }
        return _fixed_string(value);
    } else if constexpr (treat_as_inexact_v<Rep>) {
        return _fixed_string(_db_double<Precision>(count));
    } else {
        constexpr int places = _decimal_places(Precision::num, Precision::den);
        if constexpr (places == 0) {
            return std::to_string(count);
        } else {
            const bool negative = count < Rep(0);
            // Compute the magnitude in unsigned arithmetic so that the most
            // negative representable count does not overflow on negation.
            const unsigned long long magnitude =
                negative ? 0ULL - static_cast<unsigned long long>(count) : static_cast<unsigned long long>(count);
 
            const unsigned long long whole = magnitude / Precision::den;
            const unsigned long long frac = magnitude % Precision::den;
 
            std::string frac_digits = std::to_string(frac);
            frac_digits.insert(0, static_cast<size_t>(places) - frac_digits.size(), '0');
 
            return (negative ? "-" : "") + std::to_string(whole) + "." + frac_digits;
        }
    }
}
template<typename Rep, typename Precision>
    requires _is_decimal_precision<typename Precision::type>
inline std::string to_string(const quantity<decibel_unit, Rep, Precision>& g) {
    return _format_db<typename Precision::type>(g.count()) + decibel_unit::symbol;
}
 
template<typename Rep, typename Precision>
    requires _is_decimal_precision<typename Precision::type>
inline std::string to_string(const quantity<decibel_unit, Rep, Precision>& g, base_unit_t) {
    return _fixed_string(_db_double<typename Precision::type>(g.count())) + decibel_unit::symbol;
}
 
template<typename Rep, typename Precision>
    requires _is_decimal_precision<typename Precision::type>
inline std::string to_string(const quantity<decibel_unit, Rep, Precision>& g, scaled_t) {
    return to_string(g, base_unit);
}
 
template<typename Reference, typename Rep, typename Precision>
    requires _is_decimal_precision<typename Precision::type>
inline std::string to_string(const level<Reference, Rep, Precision>& l) {
    return _format_db<typename Precision::type>(l.count()) + Reference::symbol;
}
 
template<typename Reference, typename Rep, typename Precision>
    requires _is_decimal_precision<typename Precision::type>
inline std::string to_string(const level<Reference, Rep, Precision>& l, base_unit_t) {
    return _fixed_string(_db_double<typename Precision::type>(l.count())) + Reference::symbol;
}
 
template<typename Reference, typename Rep, typename Precision>
    requires _is_decimal_precision<typename Precision::type>
inline std::string to_string(const level<Reference, Rep, Precision>& l, scaled_t) {
    return to_string(l, base_unit);
}
 
} // namespace quanta::electro
 
namespace std {
 
template<typename Reference, typename Rep1, typename Precision1, typename Rep2, typename Precision2>
struct common_type<
    quanta::electro::level<Reference, Rep1, Precision1>,
    quanta::electro::level<Reference, Rep2, Precision2>> {
private:
    using common_offset =
        std::common_type_t<quanta::electro::gain<Rep1, Precision1>, quanta::electro::gain<Rep2, Precision2>>;
 
public:
    using type = quanta::electro::level<Reference, typename common_offset::rep, typename common_offset::precision>;
};
 
} // namespace std
 
#if CONFIG_QUANTA_STD_FORMAT
namespace quanta::electro {
 
// Shared formatter for gains and levels. "{}" renders the exact value as a
// fixed-point decimal ("10.50dB"). A non-empty spec controls only how the
// value (in decibels, as double) is rendered, never the unit:
// std::format("{:.1f}", 1050_cdB) == "10.5dB". The 'b' and 's' markers are
// accepted for consistency with the other quantities; decibels have no other
// unit, so they render in the same unit, and with nothing after the marker
// the value is rendered in the shortest fixed notation that round-trips:
// std::format("{:b}", 1050_cdB) == "10.5dB".
template<typename Precision>
struct _db_formatter {
private:
    std::formatter<double> _num;
    bool _has_spec = false;
    bool _marker = false;
 
public:
    constexpr auto parse(std::format_parse_context& ctx) {
        _marker = detail::_parse_unit_marker(ctx, "bs") != detail::_unit_form::own;
        auto it = ctx.begin();
        if (it == ctx.end() || *it == '}') {
            return it;
        }
        _has_spec = true;
        return _num.parse(ctx);
    }
 
    template<typename Rep, typename FormatContext>
    auto format(const Rep& count, const char* symbol, FormatContext& ctx) const {
        auto out = ctx.out();
        if (_has_spec) {
            out = _num.format(_db_double<Precision>(count), ctx);
        } else if (_marker) {
            out = std::format_to(out, "{}", _fixed_string(_db_double<Precision>(count)));
        } else {
            out = std::format_to(out, "{}", _format_db<Precision>(count));
        }
        return _format_append(out, symbol);
    }
};
 
} // namespace quanta::electro
namespace std {
 
// See quanta::electro::_db_formatter: "{}" -> "10.50dB", "{:.1f}" -> "10.5dB".
template<typename Rep, typename Precision>
    requires quanta::electro::_is_decimal_precision<typename Precision::type>
struct formatter<quanta::electro::quantity<quanta::electro::decibel_unit, Rep, Precision>, char>
    : quanta::electro::_db_formatter<typename Precision::type> {
    template<typename FormatContext>
    auto format(
        const quanta::electro::quantity<quanta::electro::decibel_unit, Rep, Precision>& g,
        FormatContext& ctx
    ) const {
        return quanta::electro::_db_formatter<typename Precision::type>::format(
            g.count(), quanta::electro::decibel_unit::symbol, ctx
        );
    }
};
 
// See quanta::electro::_db_formatter; the level's reference symbol is appended
// ("13.01dBm", "{:.1f}" -> "13.0dBm").
template<typename Reference, typename Rep, typename Precision>
    requires quanta::electro::_is_decimal_precision<typename Precision::type>
struct formatter<quanta::electro::level<Reference, Rep, Precision>, char>
    : quanta::electro::_db_formatter<typename Precision::type> {
    template<typename FormatContext>
    auto format(const quanta::electro::level<Reference, Rep, Precision>& l, FormatContext& ctx) const {
        return quanta::electro::_db_formatter<typename Precision::type>::format(l.count(), Reference::symbol, ctx);
    }
};
 
} // namespace std
#endif
 
namespace quanta {
inline namespace literals {
inline namespace electro_literals {
 
template<char... Digits>
constexpr quanta::electro::decibels operator""_dB() {
    return detail::check_overflow<quanta::electro::decibels, Digits...>();
}
 
template<char... Digits>
constexpr quanta::electro::centidecibels operator""_cdB() {
    return detail::check_overflow<quanta::electro::centidecibels, Digits...>();
}
 
template<char... Digits>
constexpr quanta::electro::dbm operator""_dBm() {
    return quanta::electro::dbm(detail::check_overflow<quanta::electro::decibels, Digits...>());
}
 
template<char... Digits>
constexpr quanta::electro::centi_dbm operator""_cdBm() {
    return quanta::electro::centi_dbm(detail::check_overflow<quanta::electro::centidecibels, Digits...>());
}
 
template<char... Digits>
constexpr quanta::electro::dbw operator""_dBW() {
    return quanta::electro::dbw(detail::check_overflow<quanta::electro::decibels, Digits...>());
}
 
template<char... Digits>
constexpr quanta::electro::dbv operator""_dBV() {
    return quanta::electro::dbv(detail::check_overflow<quanta::electro::decibels, Digits...>());
}
 
template<char... Digits>
constexpr quanta::electro::dbmv operator""_dBmV() {
    return quanta::electro::dbmv(detail::check_overflow<quanta::electro::decibels, Digits...>());
}
 
template<char... Digits>
constexpr quanta::electro::dbuv operator""_dBuV() {
    return quanta::electro::dbuv(detail::check_overflow<quanta::electro::decibels, Digits...>());
}
 
#if QUANTA_HAS_UTF8_LITERALS
template<char... Digits>
constexpr quanta::electro::dbuv operator""_dBµV() {
    return quanta::electro::dbuv(detail::check_overflow<quanta::electro::decibels, Digits...>());
}
#endif
 
} // namespace electro_literals
} // namespace literals
 
namespace electro {
using namespace literals::electro_literals;
} // namespace electro
} // namespace quanta