freq Namespace Reference

Frequency types and utilities. More...

Classes
class	frequency
	A frequency value with a representation and precision. More...
struct	is_frequency
	Trait to detect frequency specializations. More...
struct	is_frequency< frequency< Rep, Precision > >

Typedefs
using	millihertz = frequency< int64_t, std::milli >
	Frequency with 0.001 Hz (millihertz) precision.
using	hertz = frequency< int64_t >
	Frequency with 1 Hz precision.
using	kilohertz = frequency< int64_t, std::kilo >
	Frequency with 1000 Hz (kilohertz) precision.
using	megahertz = frequency< int64_t, std::mega >
	Frequency with 1,000,000 Hz (megahertz) precision.
using	gigahertz = frequency< int64_t, std::giga >
	Frequency with 1,000,000,000 Hz (gigahertz) precision.
using	terahertz = frequency< int64_t, std::tera >
	Frequency with 1,000,000,000,000 Hz (terahertz) precision.

Functions
template<typename ToFreq , typename Rep , typename Precision >
constexpr ToFreq	frequency_cast (const frequency< Rep, Precision > &f)
	Converts a frequency to a different precision or representation.
template<typename ToFreq , typename Rep , typename Precision >
constexpr ToFreq	floor (const frequency< Rep, Precision > &f)
	Converts a frequency to the target type, rounding toward negative infinity.
template<typename ToFreq , typename Rep , typename Precision >
constexpr ToFreq	ceil (const frequency< Rep, Precision > &f)
	Converts a frequency to the target type, rounding toward positive infinity.
template<typename ToFreq , typename Rep , typename Precision >
constexpr ToFreq	round (const frequency< Rep, Precision > &f)
	Converts a frequency to the target type, rounding to nearest (ties to even).
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 > >
	Calculates the beat frequency between two frequencies.
template<typename Rep , typename Precision >
constexpr frequency< Rep, Precision >	abs (const frequency< Rep, Precision > &f)
	Returns the absolute value of a frequency.
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 > >
	Returns the sum of two frequencies.
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 > >
	Returns the difference of two frequencies.
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 >
	Multiplies a frequency by a scalar.
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 >
	Multiplies a scalar by a frequency.
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 >
	Divides a frequency by a scalar.
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 >
	Divides two frequencies, returning a scalar.
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 >
	Returns the remainder of dividing a frequency by a scalar.
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 > >
	Returns the remainder of dividing two frequencies.
template<typename Rep1 , typename Precision1 , typename Rep2 , typename Precision2 >
constexpr bool	operator== (const frequency< Rep1, Precision1 > &lhs, const frequency< Rep2, Precision2 > &rhs)
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)
template<typename Rep , typename Precision > requires (!treat_as_inexact_v<Rep>)
std::string	to_string (const frequency< Rep, Precision > &f)
	Renders a frequency as its exact count with a precision-qualified unit, e.g.

Variables
template<typename T >
constexpr bool	is_frequency_v = is_frequency<T>::value

Detailed Description

Frequency types and utilities.

This library provides type-safe frequency handling with support for multiple precisions (mHz, Hz, kHz, MHz, GHz, THz), following the design of std::chrono::duration.

Basic Usage

The library provides standard integer-based frequency types:

using namespace freq;
using namespace frequency_literals;
 
hertz audio_rate{44100};
kilohertz cpu_clock{3200};
auto wifi = 2400_MHz;
auto optical = 193_THz;  // Near-infrared light

Floating-Point Frequencies

For fractional precision (e.g., musical tuning, scientific measurements), use floating-point representations:

// Define floating-point frequency types
using hertz_d = frequency<double, std::ratio<1>>;
using kilohertz_d = frequency<double, std::kilo>;
using megahertz_d = frequency<double, std::mega>;
 
// Musical tuning - concert pitch
hertz_d concert_a{440.0};
hertz_d c_sharp = concert_a.semitone_shift(4);  // 554.37 Hz
 
// Scientific measurements
megahertz_d fm_station{88.5};  // 88.5 MHz
kilohertz_d middle_c{261.626}; // Middle C in Hz
 
// Fractional arithmetic
hertz_d f1{1000.5};
hertz_d f2{500.25};
hertz_d sum = f1 + f2;  // 1500.75 Hz
 
// Octave operations with fractional values
hertz_d a4{440.0};
hertz_d tritone = a4.octave_shift(0.5);  // 622.25 Hz (half octave)
hertz_d perfect_fifth = a4 * 1.5;        // 660.0 Hz (3:2 ratio)

Integer vs Floating-Point

• Integer types (default): Exact arithmetic, support modulo operations, preferred for digital systems and counting applications
• Floating-point types: Fractional precision, natural for calculations involving division and musical intervals, but no modulo operations

Conversions between integer and floating-point follow the same rules as precision conversions (implicit when lossless, explicit when lossy).

Function Documentation

abs()

template<typename Rep , typename Precision >

constexpr frequency< Rep, Precision > freq::abs ( const frequency< Rep, Precision > &  f )

constexpr

Returns the absolute value of a frequency.

Template Parameters

Rep	Representation type.
Precision	Precision type.

Parameters

f	The frequency.

Returns

The absolute value of the frequency.

using namespace freq;
hertz h{-440};
auto abs_h = abs(h);  // 440 Hz

Definition at line 977 of file frequency.hpp.

References frequency_cast(), and freq::frequency< Rep, Precision >::zero().

Referenced by beat().

beat()

template<typename Rep1 , typename Precision1 , typename Rep2 , typename Precision2 >

constexpr auto freq::beat ( const frequency< Rep1, Precision1 > &  f1, const frequency< Rep2, Precision2 > &  f2  ) -> std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>

constexpr

Calculates the beat frequency between two frequencies.

In acoustics and signal processing, the beat frequency is the absolute difference between two frequencies. When two sound waves of slightly different frequencies interfere, they produce a beating pattern at this frequency.

This is a convenience function equivalent to abs(f1 - f2).

Template Parameters

Rep1	First frequency representation type.
Precision1	First frequency precision.
Rep2	Second frequency representation type.
Precision2	Second frequency precision.

Parameters

f1	The first frequency.
f2	The second frequency.

Returns

The beat frequency as the absolute difference.

using namespace freq;
using namespace frequency_literals;
 
// Acoustic beats between two tuning forks
auto f1 = 440_Hz;  // A4 concert pitch
auto f2 = 442_Hz;  // Slightly sharp A4
auto beat = beat(f1, f2);  // 2 Hz beat
 
// Mixed precisions handled automatically
auto carrier = 1000_Hz;
auto modulator = 1_kHz + 10_Hz;
auto beat2 = beat(carrier, modulator);  // 10 Hz

See also

abs(), operator-()

Definition at line 955 of file frequency.hpp.

References abs(), and frequency_cast().

ceil()

template<typename ToFreq , typename Rep , typename Precision >

constexpr ToFreq freq::ceil ( const frequency< Rep, Precision > &  f )

constexpr

Converts a frequency to the target type, rounding toward positive infinity.

This function performs a frequency conversion with ceiling rounding semantics. When converting to a coarser precision, values are rounded up.

Template Parameters

ToFreq	The target frequency type.
Rep	Source representation type.
Precision	Source precision.

Parameters

f	The frequency to convert.

Returns

The converted frequency, rounded toward positive infinity.

using namespace freq;
hertz h{1500};
auto kh = ceil<kilohertz>(h);  // 2 kHz (rounded up from 1.5)

Definition at line 859 of file frequency.hpp.

References frequency_cast().

floor()

template<typename ToFreq , typename Rep , typename Precision >

constexpr ToFreq freq::floor ( const frequency< Rep, Precision > &  f )

constexpr

Converts a frequency to the target type, rounding toward negative infinity.

This function performs a frequency conversion with floor rounding semantics. When converting to a coarser precision, values are rounded down.

Template Parameters

ToFreq	The target frequency type.
Rep	Source representation type.
Precision	Source precision.

Parameters

f	The frequency to convert.

Returns

The converted frequency, rounded toward negative infinity.

using namespace freq;
hertz h{1500};
auto kh = floor<kilohertz>(h);  // 1 kHz (rounded down from 1.5)

Definition at line 826 of file frequency.hpp.

References frequency_cast().

frequency_cast()

template<typename ToFreq , typename Rep , typename Precision >

constexpr ToFreq freq::frequency_cast ( const frequency< Rep, Precision > &  f )

constexpr

Converts a frequency to a different precision or representation.

For integer-to-integer conversions, this function uses wider intermediate types (128-bit when available) to minimize overflow risk during ratio arithmetic.

Template Parameters

ToFreq	The target frequency type.
Rep	Source representation type.
Precision	Source precision.

Parameters

f	The frequency to convert.

Returns

The converted frequency.

Definition at line 750 of file frequency.hpp.

References frequency_cast().

Referenced by abs(), beat(), ceil(), floor(), frequency_cast(), freq::frequency< Rep, Precision >::harmonic(), freq::frequency< Rep, Precision >::octave_shift(), freq::frequency< Rep, Precision >::octaves_from(), operator%(), operator%(), freq::frequency< Rep, Precision >::operator%=(), freq::frequency< Rep, Precision >::operator%=(), operator*(), operator*(), freq::frequency< Rep, Precision >::operator*=(), operator+(), freq::frequency< Rep, Precision >::operator+=(), operator-(), freq::frequency< Rep, Precision >::operator-=(), operator/(), operator/(), freq::frequency< Rep, Precision >::operator/=(), operator<=>(), operator==(), freq::frequency< Rep, Precision >::period(), round(), freq::frequency< Rep, Precision >::semitone_shift(), freq::frequency< Rep, Precision >::semitones_from(), freq::frequency< Rep, Precision >::subharmonic(), to_string(), freq::frequency< Rep, Precision >::wavelength(), and freq::frequency< Rep, Precision >::wavelength().

operator%() [1/2]

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 freq::operator% ( const frequency< Rep1, Precision > &  f, const Rep2 &  s  ) -> frequency<std::common_type_t<Rep1, Rep2>, Precision>

constexpr

Returns the remainder of dividing a frequency by a scalar.

Definition at line 1035 of file frequency.hpp.

References frequency_cast().

operator%() [2/2]

template<typename Rep1 , typename Precision1 , typename Rep2 , typename Precision2 >
requires (!treat_as_inexact_v<Rep1> && !treat_as_inexact_v<Rep2>)

constexpr auto freq::operator% ( const frequency< Rep1, Precision1 > &  lhs, const frequency< Rep2, Precision2 > &  rhs  ) -> std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>

constexpr

Returns the remainder of dividing two frequencies.

Definition at line 1044 of file frequency.hpp.

References frequency_cast().

operator*() [1/2]

template<typename Rep1 , typename Precision , typename Rep2 >
requires not_frequency<Rep2> && std::convertible_to<const Rep2&, std::common_type_t<Rep1, Rep2>>

constexpr auto freq::operator* ( const frequency< Rep1, Precision > &  f, const Rep2 &  r  ) -> frequency<std::common_type_t<Rep1, Rep2>, Precision>

constexpr

Multiplies a frequency by a scalar.

Definition at line 1000 of file frequency.hpp.

References frequency_cast().

operator*() [2/2]

template<typename Rep1 , typename Rep2 , typename Precision >
requires not_frequency<Rep1> && std::convertible_to<const Rep1&, std::common_type_t<Rep1, Rep2>>

constexpr auto freq::operator* ( const Rep1 &  r, const frequency< Rep2, Precision > &  f  ) -> frequency<std::common_type_t<Rep1, Rep2>, Precision>

constexpr

Multiplies a scalar by a frequency.

Definition at line 1009 of file frequency.hpp.

References frequency_cast().

operator+()

template<typename Rep1 , typename Precision1 , typename Rep2 , typename Precision2 >

constexpr auto freq::operator+ ( const frequency< Rep1, Precision1 > &  lhs, const frequency< Rep2, Precision2 > &  rhs  ) -> std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>

constexpr

Returns the sum of two frequencies.

Definition at line 983 of file frequency.hpp.

References frequency_cast().

operator-()

template<typename Rep1 , typename Precision1 , typename Rep2 , typename Precision2 >

constexpr auto freq::operator- ( const frequency< Rep1, Precision1 > &  lhs, const frequency< Rep2, Precision2 > &  rhs  ) -> std::common_type_t<frequency<Rep1, Precision1>, frequency<Rep2, Precision2>>

constexpr

Returns the difference of two frequencies.

Definition at line 991 of file frequency.hpp.

References frequency_cast().

operator/() [1/2]

template<typename Rep1 , typename Precision , typename Rep2 >
requires not_frequency<Rep2> && std::convertible_to<const Rep2&, std::common_type_t<Rep1, Rep2>>

constexpr auto freq::operator/ ( const frequency< Rep1, Precision > &  f, const Rep2 &  s  ) -> frequency<std::common_type_t<Rep1, Rep2>, Precision>

constexpr

Divides a frequency by a scalar.

Definition at line 1017 of file frequency.hpp.

References frequency_cast().

operator/() [2/2]

template<typename Rep1 , typename Precision1 , typename Rep2 , typename Precision2 >

constexpr auto freq::operator/ ( const frequency< Rep1, Precision1 > &  lhs, const frequency< Rep2, Precision2 > &  rhs  ) -> std::common_type_t<Rep1, Rep2>

constexpr

Divides two frequencies, returning a scalar.

Definition at line 1025 of file frequency.hpp.

References freq::frequency< Rep, Precision >::count(), and frequency_cast().

operator<=>()

template<typename Rep1 , typename Precision1 , typename Rep2 , typename Precision2 >
requires std::three_way_comparable<std::common_type_t<Rep1, Rep2>>

constexpr auto freq::operator<=> ( const frequency< Rep1, Precision1 > &  lhs, const frequency< Rep2, Precision2 > &  rhs  )

constexpr

Definition at line 1058 of file frequency.hpp.

References freq::frequency< Rep, Precision >::count(), and frequency_cast().

operator==()

template<typename Rep1 , typename Precision1 , typename Rep2 , typename Precision2 >

constexpr bool freq::operator== ( const frequency< Rep1, Precision1 > &  lhs, const frequency< Rep2, Precision2 > &  rhs  )

constexpr

Definition at line 1051 of file frequency.hpp.

References freq::frequency< Rep, Precision >::count(), and frequency_cast().

round()

template<typename ToFreq , typename Rep , typename Precision >

constexpr ToFreq freq::round ( const frequency< Rep, Precision > &  f )

constexpr

Converts a frequency to the target type, rounding to nearest (ties to even).

This function performs a frequency conversion with round-to-nearest rounding semantics. When converting to a coarser precision, values are rounded to the nearest representable value, with ties rounded to even.

Template Parameters

ToFreq	The target frequency type.
Rep	Source representation type.
Precision	Source precision.

Parameters

f	The frequency to convert.

Returns

The converted frequency, rounded to nearest.

using namespace freq;
hertz h1{1500};
hertz h2{2500};
auto kh1 = round<kilohertz>(h1);  // 2 kHz (rounded to even)
auto kh2 = round<kilohertz>(h2);  // 2 kHz (rounded to even)

Definition at line 895 of file frequency.hpp.

References frequency_cast().

to_string()

template<typename Rep , typename Precision >
requires (!treat_as_inexact_v<Rep>)

std::string freq::to_string

(

const frequency< Rep, Precision > &

f

)

Renders a frequency as its exact count with a precision-qualified unit, e.g.

to_string(kilohertz(433)) == "433kHz".

Definition at line 1187 of file frequency.hpp.

References frequency_cast().

Variable Documentation

is_frequency_v

template<typename T >

constexpr bool freq::is_frequency_v = is_frequency<T>::value

inlineconstexpr

Definition at line 105 of file frequency.hpp.