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 > requires detail::_quantity_cast_requirements<frequency<Rep, Precision>, ToFreq>
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	trunc (const frequency< Rep, Precision > &f)
	Converts a frequency to the target type, rounding toward zero.

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 >
std::string	to_string (const frequency< Rep, Precision > &f)
	Converts a frequency to a string with its precision-qualified unit.

template<typename Rep , typename Precision >
std::string	to_string (const frequency< Rep, Precision > &f, base_unit_t)
	Converts a frequency to a string in hertz; see base_unit.

template<typename Rep , typename Precision >
std::string	to_string (const frequency< Rep, Precision > &f, scaled_t)
	Converts a frequency to a string with an SI prefix scaled to its magnitude; see scaled.

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 quanta::frequency;
using namespace quanta::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).

Formatting

to_string() and std::format show a frequency in its own unit by default, whatever the format spec: {} prints the exact count and {:.1f} the count as a double, each followed by the precision's SI-prefixed unit. A single leading marker letter in the spec, or a tag argument to to_string(), opts into a different unit:

std::format("{}", millihertz(1500));      // "1500mHz"   own unit
std::format("{:.1f}", millihertz(1500));  // "1500.0mHz" own unit
std::format("{:b}", millihertz(1500));    // "1.5Hz"     base unit (hertz)
std::format("{:s}", megahertz(2400));     // "2.4GHz"    scaled
std::format("{:s.2f}", hertz(1500));      // "1.50kHz"
to_string(megahertz(2400), scaled);       // "2.4GHz"

A precision with no SI prefix (e.g. std::deci) has no unit of its own: {} and to_string(f) do not compile for it, and a format spec without a marker renders the value in hertz.

Function Documentation

◆ abs()

template<typename Rep , typename Precision >

constexpr frequency< Rep, Precision > quanta::frequency::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 quanta::frequency;
hertz h{-440};
auto abs_h = abs(h);  // 440 Hz

Definition at line 871 of file frequency.hpp.

Referenced by beat().

◆ beat()

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

constexpr auto quanta::frequency::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 quanta::frequency;
using namespace quanta::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 849 of file frequency.hpp.

References abs().

◆ ceil()

template<typename ToFreq , typename Rep , typename Precision >

constexpr ToFreq quanta::frequency::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.

As with the cast, the result is undefined if it does not fit the target rep.

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 quanta::frequency;
hertz h{1500};
auto kh = ceil<kilohertz>(h);  // 2 kHz (rounded up from 1.5)

Definition at line 758 of file frequency.hpp.

◆ floor()

template<typename ToFreq , typename Rep , typename Precision >

constexpr ToFreq quanta::frequency::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.

As with the cast, the result is undefined if it does not fit the target rep.

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 quanta::frequency;
hertz h{1500};
auto kh = floor<kilohertz>(h);  // 1 kHz (rounded down from 1.5)

Definition at line 732 of file frequency.hpp.

◆ frequency_cast()

template<typename ToFreq , typename Rep , typename Precision >
requires detail::_quantity_cast_requirements<frequency<Rep, Precision>, ToFreq>

constexpr ToFreq quanta::frequency::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 706 of file frequency.hpp.

◆ 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 quanta::frequency::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 929 of file frequency.hpp.

◆ 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 quanta::frequency::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 938 of file frequency.hpp.

◆ 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 quanta::frequency::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 894 of file frequency.hpp.

◆ 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 quanta::frequency::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 903 of file frequency.hpp.

◆ operator+()

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

constexpr auto quanta::frequency::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 877 of file frequency.hpp.

◆ operator-()

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

constexpr auto quanta::frequency::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 885 of file frequency.hpp.

◆ 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 quanta::frequency::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 911 of file frequency.hpp.

◆ operator/() [2/2]

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

constexpr auto quanta::frequency::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 919 of file frequency.hpp.

References quanta::frequency::frequency< Rep, Precision >::count().

◆ operator<=>()

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

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

constexpr

Definition at line 952 of file frequency.hpp.

References quanta::frequency::frequency< Rep, Precision >::count().

◆ operator==()

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

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

constexpr

Definition at line 945 of file frequency.hpp.

References quanta::frequency::frequency< Rep, Precision >::count().

◆ round()

template<typename ToFreq , typename Rep , typename Precision >

constexpr ToFreq quanta::frequency::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.

As with the cast, the result is undefined if it does not fit the target rep.

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 quanta::frequency;
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 809 of file frequency.hpp.

◆ to_string() [1/3]

template<typename Rep , typename Precision >

std::string quanta::frequency::to_string ( const frequency< Rep, Precision > & f )

Converts a frequency to a string with its precision-qualified unit.

Integer counts are shown exactly; floating-point counts in the shortest fixed notation that round-trips (never scientific), matching std::format("{}"). Available for precisions with an SI prefix (femto to tera); for other precisions use the base_unit or scaled form.

to_string(kilohertz(433));              // "433kHz"
to_string(millihertz(1500));            // "1500mHz"
to_string(frequency<double>(1e6));      // "1000000Hz"
to_string(frequency<double, std::kilo>(2.5)); // "2.5kHz"

Definition at line 1189 of file frequency.hpp.

References quanta::frequency::frequency< Rep, Precision >::count().

◆ to_string() [2/3]

template<typename Rep , typename Precision >

std::string quanta::frequency::to_string	(	const frequency< Rep, Precision > &	f,
		base_unit_t
	)

Converts a frequency to a string in hertz; see base_unit.

Available for every precision.

to_string(millihertz(1500), base_unit); // "1.5Hz"

Definition at line 1205 of file frequency.hpp.

◆ to_string() [3/3]

template<typename Rep , typename Precision >

std::string quanta::frequency::to_string	(	const frequency< Rep, Precision > &	f,
		scaled_t
	)

Converts a frequency to a string with an SI prefix scaled to its magnitude; see scaled.

Available for every precision.

to_string(megahertz(2400), scaled); // "2.4GHz"

Definition at line 1221 of file frequency.hpp.

◆ trunc()

template<typename ToFreq , typename Rep , typename Precision >

constexpr ToFreq quanta::frequency::trunc ( const frequency< Rep, Precision > & f )

constexpr

Converts a frequency to the target type, rounding toward zero.

The same as frequency_cast<ToFreq>(f).

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 zero.

using namespace quanta::frequency;

auto kh = trunc<kilohertz>(hertz(-1500)); // -1 kHz (rounded toward zero from -1.5)

Definition at line 780 of file frequency.hpp.

Variable Documentation

◆ is_frequency_v

template<typename T >

constexpr bool quanta::frequency::is_frequency_v = is_frequency<T>::value

inlineconstexpr

Definition at line 125 of file frequency.hpp.

Classes

Typedefs

Functions

Variables

Detailed Description

Basic Usage

Floating-Point Frequencies

Integer vs Floating-Point

Formatting

Function Documentation

◆ abs()

◆ beat()

◆ ceil()

◆ floor()

◆ frequency_cast()

◆ operator%() [1/2]

◆ operator%() [2/2]

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator+()

◆ operator-()

◆ operator/() [1/2]

◆ operator/() [2/2]

◆ operator<=>()

◆ operator==()

◆ round()

◆ to_string() [1/3]

◆ to_string() [2/3]

◆ to_string() [3/3]

◆ trunc()

Variable Documentation

◆ is_frequency_v