frequency: 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)

std::string	to_string (millihertz f)

std::string	to_string (hertz f)

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;

auto optical = 193_THz;

A frequency value with a representation and precision.

Frequency types and utilities.

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

Converts a frequency to a different precision or representation.

User-defined literals for frequency types.

Floating-Point Frequencies

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

frequency semitone_shift(T semitones) const

Returns this frequency shifted by a number of semitones.

frequency octave_shift(T octaves) const

Returns this frequency shifted by a number of octaves.

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

◆ abs()

Returns the absolute value of a frequency.

Template Parameters

Rep	Representation type.
Precision	Precision type.

Parameters

Returns: The absolute value of the frequency.

using namespace freq;

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

Returns the absolute value of a frequency.

Definition at line 976 of file frequency.hpp.

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

Referenced by beat().

◆ beat()

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;

auto f1 = 440_Hz;

auto f2 = 442_Hz;

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.

See also: abs(), operator-()

Definition at line 954 of file frequency.hpp.

References abs(), and frequency_cast().

◆ ceil()

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.

Definition at line 858 of file frequency.hpp.

References frequency_cast().

◆ floor()

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.

Definition at line 825 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 > &

)

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 749 of file frequency.hpp.

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

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.

Definition at line 894 of file frequency.hpp.

References frequency_cast().

◆ to_string() [1/2]

std::string freq::to_string

(

hertz

)

inline

◆ to_string() [2/2]

std::string freq::to_string

(

millihertz

)

inline

Classes

Typedefs

Functions

Basic Usage

Floating-Point Frequencies

Integer vs Floating-Point

◆ 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/2]

◆ to_string() [2/2]

◆ is_frequency_v