A frequency value with a representation and precision. More...

#include <frequency/frequency.hpp>

Public Types
using	rep = Rep
	The representation type.

using	precision = typename Precision::type
	The precision as a std::ratio.

Public Member Functions
constexpr	frequency ()=default
	Constructs a zero frequency.

	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	frequency (const Rep2 &r)
	Constructs from a tick count.

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)
	Constructs from another frequency with different representation or precision.

template<typename Rep2 , typename Precision2 > requires (!std::is_same_v<frequency, frequency<Rep2, Precision2>>) && (!treat_as_inexact_v<rep>) && (!_harmonic_precision<Precision2, precision>)
constexpr	frequency (const frequency< Rep2, Precision2 > &f)
	Explicit constructor for lossy precision conversions.

	~frequency ()=default

frequency &	operator= (const frequency &)=default

constexpr rep	count () const
	Returns the tick count.

constexpr frequency< typename std::common_type< rep >::type, precision >	operator+ () const

constexpr frequency< typename std::common_type< rep >::type, precision >	operator- () const

constexpr frequency &	operator++ ()

constexpr frequency	operator++ (int)

constexpr frequency &	operator-- ()

constexpr frequency	operator-- (int)

constexpr frequency &	operator+= (const frequency &f)

constexpr frequency &	operator-= (const frequency &f)

constexpr frequency &	operator*= (const rep &r)

constexpr frequency &	operator/= (const rep &r)

constexpr frequency &	operator%= (const rep &r)

constexpr frequency &	operator%= (const frequency &f)

template<duration_like Duration>
constexpr Duration	period () const
	Returns the period of this frequency as a duration.

constexpr frequency	harmonic (unsigned int n) const
	Returns the nth harmonic of this frequency.

constexpr frequency	subharmonic (unsigned int n) const
	Returns the nth subharmonic of this frequency.

template<typename T = double>
frequency	octave_shift (T octaves) const
	Returns this frequency shifted by a number of octaves.

template<typename T = double>
frequency	semitone_shift (T semitones) const
	Returns this frequency shifted by a number of semitones.

template<typename T = double>
T	octaves_from (const frequency &other) const
	Calculates the interval in octaves between this frequency and another.

template<typename T = double>
T	semitones_from (const frequency &other) const
	Calculates the interval in semitones between this frequency and another.

template<distance_like Distance, duration_like Duration>
constexpr Distance	wavelength (const Duration &time_per_unit_distance) const
	Calculates the wavelength for this frequency.

template<distance_like Distance>
constexpr Distance	wavelength (double velocity=299792458.0) const
	Calculates the wavelength for this frequency given a propagation velocity.

Static Public Member Functions
static constexpr frequency	zero () noexcept
	Returns a zero frequency.

static constexpr frequency	min () noexcept
	Returns the minimum representable frequency.

static constexpr frequency	max () noexcept
	Returns the maximum representable frequency.

Detailed Description

template<typename Rep, typename Precision>
class freq::frequency< Rep, Precision >

A frequency value with a representation and precision.

Similar to std::chrono::duration, frequency represents a quantity of cycles per second. The precision is expressed as a std::ratio of one Hertz.

Basic Examples

// Integer frequencies (default)
hertz audio{44100};
kilohertz cpu{3200};
auto wifi = 2400_MHz;
 
// Arithmetic
auto sum = 1000_Hz + 500_Hz;  // 1500 Hz
auto scaled = 100_Hz * 3;     // 300 Hz
auto ratio = 1000_Hz / 100_Hz; // 10 (scalar)

Floating-Point Examples

// Define floating-point types
using hertz_d = frequency<double>;
using kilohertz_d = frequency<double, std::kilo>;
 
// Fractional values
hertz_d concert_pitch{440.0};
hertz_d a_flat = concert_pitch.semitone_shift(-1);  // 415.30 Hz
 
// Exact ratios for just intonation
hertz_d fundamental{100.0};
hertz_d perfect_fifth = fundamental * 1.5;  // 3:2 ratio
hertz_d major_third = fundamental * 1.25;   // 5:4 ratio
 
// Scientific measurements
kilohertz_d am_radio{540.5};  // 540.5 kHz

Template Parameters

Rep	Arithmetic type for the tick count.
Precision	A std::ratio representing the precision (default: 1 Hz).

Definition at line 281 of file frequency.hpp.

Member Typedef Documentation

◆ precision

template<typename Rep , typename Precision >

using freq::frequency< Rep, Precision >::precision = typename Precision::type

The precision as a std::ratio.

Definition at line 290 of file frequency.hpp.

◆ rep

template<typename Rep , typename Precision >

using freq::frequency< Rep, Precision >::rep = Rep

The representation type.

Definition at line 288 of file frequency.hpp.

Constructor & Destructor Documentation

◆ frequency() [1/5]

template<typename Rep , typename Precision >

constexpr freq::frequency< Rep, Precision >::frequency ( )

constexprdefault

Constructs a zero frequency.

Referenced by freq::frequency< Rep, Precision >::max(), freq::frequency< Rep, Precision >::min(), freq::frequency< Rep, Precision >::octave_shift(), freq::frequency< Rep, Precision >::operator++(), freq::frequency< Rep, Precision >::operator--(), freq::frequency< Rep, Precision >::semitone_shift(), and freq::frequency< Rep, Precision >::zero().

◆ frequency() [2/5]

template<typename Rep , typename Precision >

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

default

◆ frequency() [3/5]

template<typename Rep , typename Precision >

template<typename Rep2 >
requires std::convertible_to<const Rep2&, rep> && (treat_as_inexact_v<rep> || !treat_as_inexact_v<Rep2>)

constexpr freq::frequency< Rep, Precision >::frequency ( const Rep2 & r )

inlineexplicitconstexpr

Constructs from a tick count.

Implicit for inexact types, explicit otherwise to prevent accidental precision loss.

Template Parameters

Rep2	The source representation type.

Parameters

r	The tick count.

Definition at line 307 of file frequency.hpp.

◆ frequency() [4/5]

template<typename Rep , typename Precision >

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 freq::frequency< Rep, Precision >::frequency ( const frequency< Rep2, Precision2 > & f )

inlineconstexpr

Constructs from another frequency with different representation or precision.

Implicit when the conversion is lossless (target precision evenly divides source precision).

Template Parameters

Rep2	Source representation type.
Precision2	Source precision.

Parameters

f	The source frequency.

Definition at line 323 of file frequency.hpp.

◆ frequency() [5/5]

template<typename Rep , typename Precision >

template<typename Rep2 , typename Precision2 >
requires (!std::is_same_v<frequency, frequency<Rep2, Precision2>>) && (!treat_as_inexact_v<rep>) && (!_harmonic_precision<Precision2, precision>)

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

inlineexplicitconstexpr

Explicit constructor for lossy precision conversions.

Template Parameters

Rep2	Source representation type.
Precision2	Source precision.

Parameters

f	The source frequency.

Definition at line 336 of file frequency.hpp.

◆ ~frequency()

template<typename Rep , typename Precision >

freq::frequency< Rep, Precision >::~frequency ( )

default

Member Function Documentation

◆ count()

template<typename Rep , typename Precision >

constexpr rep freq::frequency< Rep, Precision >::count ( ) const

inlineconstexpr

Returns the tick count.

Definition at line 343 of file frequency.hpp.

Referenced by freq::operator/(), freq::operator<=>(), freq::operator==(), and freq::frequency< Rep, Precision >::period().

◆ harmonic()

template<typename Rep , typename Precision >

constexpr frequency freq::frequency< Rep, Precision >::harmonic ( unsigned int n ) const

inlineconstexpr

Returns the nth harmonic of this frequency.

The nth harmonic is n times the fundamental frequency. For example, the 2nd harmonic of 440 Hz is 880 Hz.

This method provides a semantically clear way to express harmonic relationships, equivalent to freq * n.

Parameters

n	The harmonic number (must be positive).

Returns: A frequency representing the nth harmonic.

Definition at line 522 of file frequency.hpp.

References freq::frequency_cast().

◆ max()

template<typename Rep , typename Precision >

static constexpr frequency freq::frequency< Rep, Precision >::max ( )

inlinestaticconstexprnoexcept

Returns the maximum representable frequency.

Definition at line 408 of file frequency.hpp.

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

◆ min()

template<typename Rep , typename Precision >

static constexpr frequency freq::frequency< Rep, Precision >::min ( )

inlinestaticconstexprnoexcept

Returns the minimum representable frequency.

Definition at line 405 of file frequency.hpp.

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

◆ octave_shift()

template<typename Rep , typename Precision >

template<typename T = double>

frequency freq::frequency< Rep, Precision >::octave_shift ( T octaves ) const

inline

Returns this frequency shifted by a number of octaves.

Shifts the frequency up or down by the specified number of octaves. Each octave represents a doubling (positive) or halving (negative) of frequency. For example, shifting 440 Hz up by 1 octave yields 880 Hz.

Fractional octaves are supported and particularly useful with floating-point types:

// Integer types round to nearest
hertz a4{440};
auto tritone = a4.octave_shift(0.5);  // 622 Hz (rounded)
 
// Floating-point types preserve fractional values
using hertz_d = frequency<double>;
hertz_d a4_d{440.0};
auto tritone_d = a4_d.octave_shift(0.5);  // 622.254 Hz (exact)

Template Parameters

T	The type of the octave value (default: double).

Parameters

octaves The number of octaves to shift (positive = up, negative = down).

Returns: A frequency representing this frequency shifted by the specified octaves.

Definition at line 565 of file frequency.hpp.

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

◆ octaves_from()

template<typename Rep , typename Precision >

template<typename T = double>

T freq::frequency< Rep, Precision >::octaves_from ( const frequency< Rep, Precision > & other ) const

inline

Calculates the interval in octaves between this frequency and another.

Returns the number of octaves between this frequency and the other frequency. Positive values indicate this frequency is higher, negative values indicate lower. For example, octaves_from(440 Hz) called on 880 Hz returns 1.0 (one octave higher).

Template Parameters

T	The return type for the octave count (default: double).

Parameters

other The reference frequency to compare against.

Returns: The number of octaves between the two frequencies.

Definition at line 620 of file frequency.hpp.

References freq::frequency_cast().

◆ operator%=() [1/2]

template<typename Rep , typename Precision >

constexpr frequency & freq::frequency< Rep, Precision >::operator%= ( const frequency< Rep, Precision > & f )

inlineconstexpr

Definition at line 394 of file frequency.hpp.

References freq::frequency_cast().

◆ operator%=() [2/2]

template<typename Rep , typename Precision >

constexpr frequency & freq::frequency< Rep, Precision >::operator%= ( const rep & r )

inlineconstexpr

Definition at line 387 of file frequency.hpp.

References freq::frequency_cast().

◆ operator*=()

template<typename Rep , typename Precision >

constexpr frequency & freq::frequency< Rep, Precision >::operator*= ( const rep & r )

inlineconstexpr

Definition at line 377 of file frequency.hpp.

References freq::frequency_cast().

◆ operator+()

template<typename Rep , typename Precision >

constexpr frequency< typename std::common_type< rep >::type, precision > freq::frequency< Rep, Precision >::operator+ ( ) const

inlineconstexpr

Definition at line 345 of file frequency.hpp.

◆ operator++() [1/2]

template<typename Rep , typename Precision >

constexpr frequency & freq::frequency< Rep, Precision >::operator++ ( )

inlineconstexpr

Definition at line 353 of file frequency.hpp.

◆ operator++() [2/2]

template<typename Rep , typename Precision >

constexpr frequency freq::frequency< Rep, Precision >::operator++ ( int )

inlineconstexpr

Definition at line 358 of file frequency.hpp.

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

◆ operator+=()

template<typename Rep , typename Precision >

constexpr frequency & freq::frequency< Rep, Precision >::operator+= ( const frequency< Rep, Precision > & f )

inlineconstexpr

Definition at line 367 of file frequency.hpp.

References freq::frequency_cast().

◆ operator-()

template<typename Rep , typename Precision >

constexpr frequency< typename std::common_type< rep >::type, precision > freq::frequency< Rep, Precision >::operator- ( ) const

inlineconstexpr

Definition at line 349 of file frequency.hpp.

◆ operator--() [1/2]

template<typename Rep , typename Precision >

constexpr frequency & freq::frequency< Rep, Precision >::operator-- ( )

inlineconstexpr

Definition at line 360 of file frequency.hpp.

◆ operator--() [2/2]

template<typename Rep , typename Precision >

constexpr frequency freq::frequency< Rep, Precision >::operator-- ( int )

inlineconstexpr

Definition at line 365 of file frequency.hpp.

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

◆ operator-=()

template<typename Rep , typename Precision >

constexpr frequency & freq::frequency< Rep, Precision >::operator-= ( const frequency< Rep, Precision > & f )

inlineconstexpr

Definition at line 372 of file frequency.hpp.

References freq::frequency_cast().

◆ operator/=()

template<typename Rep , typename Precision >

constexpr frequency & freq::frequency< Rep, Precision >::operator/= ( const rep & r )

inlineconstexpr

Definition at line 382 of file frequency.hpp.

References freq::frequency_cast().

◆ operator=()

template<typename Rep , typename Precision >

frequency & freq::frequency< Rep, Precision >::operator= ( const frequency< Rep, Precision > & )

default

◆ period()

template<typename Rep , typename Precision >

template<duration_like Duration>

constexpr Duration freq::frequency< Rep, Precision >::period ( ) const

inlineconstexpr

Returns the period of this frequency as a duration.

The period is the inverse of the frequency. For example, a frequency of 1000 Hz has a period of 1 millisecond.

For integer-to-integer conversions, this method uses exact integer arithmetic with wider intermediate types (128-bit when available) to minimize overflow risk. Common conversions like hertz{1000} to milliseconds will produce exact results.

When either the frequency or duration uses floating-point representation, the calculation falls back to floating-point arithmetic.

Template Parameters

Duration The target duration type. Must satisfy the duration_like concept.

Returns: The period as a duration.

Note: For integer duration types, be aware that the result may truncate if the exact period is not representable (e.g., gigahertz{2}.period<nanoseconds>() truncates to 0 since the true period is 0.5 ns).

// Integer-to-integer conversions (exact)
hertz{1000}.period<std::chrono::milliseconds>()   // exactly 1 ms
kilohertz{1}.period<std::chrono::milliseconds>()  // exactly 1 ms
hertz{100}.period<std::chrono::microseconds>()    // exactly 10 µs
 
// Floating-point for fractional precision
using hertz_d = frequency<double>;
hertz_d{440.0}.period<std::chrono::duration<double, std::milli>>() // ~2.27 ms

Definition at line 442 of file frequency.hpp.

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

◆ semitone_shift()

template<typename Rep , typename Precision >

template<typename T = double>

frequency freq::frequency< Rep, Precision >::semitone_shift ( T semitones ) const

inline

Returns this frequency shifted by a number of semitones.

Shifts the frequency up or down by the specified number of semitones. There are 12 semitones per octave in equal temperament tuning. For example, shifting 440 Hz up by 12 semitones yields 880 Hz (one octave).

Fractional semitones enable precise microtonal adjustments:

using hertz_d = frequency<double>;
hertz_d a4{440.0};
 
// Equal temperament intervals
auto major_third = a4.semitone_shift(4);   // 554.37 Hz (C#)
auto perfect_fifth = a4.semitone_shift(7); // 659.26 Hz (E)
 
// Microtonal adjustment (50 cents = 0.5 semitones)
auto slightly_sharp = a4.semitone_shift(0.5);  // 452.89 Hz

Template Parameters

T	The type of the semitone value (default: double).

Parameters

semitones The number of semitones to shift (positive = up, negative = down).

Returns: A frequency representing this frequency shifted by the specified semitones.

Definition at line 599 of file frequency.hpp.

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

◆ semitones_from()

template<typename Rep , typename Precision >

template<typename T = double>

T freq::frequency< Rep, Precision >::semitones_from ( const frequency< Rep, Precision > & other ) const

inline

Calculates the interval in semitones between this frequency and another.

Returns the number of semitones between this frequency and the other frequency. There are 12 semitones per octave in equal temperament tuning. Positive values indicate this frequency is higher, negative values indicate lower.

Template Parameters

T	The return type for the semitone count (default: double).

Parameters

other The reference frequency to compare against.

Returns: The number of semitones between the two frequencies.

Definition at line 636 of file frequency.hpp.

References freq::frequency_cast().

◆ subharmonic()

template<typename Rep , typename Precision >

constexpr frequency freq::frequency< Rep, Precision >::subharmonic ( unsigned int n ) const

inlineconstexpr

Returns the nth subharmonic of this frequency.

The nth subharmonic is the fundamental frequency divided by n. For example, the 2nd subharmonic of 880 Hz is 440 Hz.

This method provides a semantically clear way to express subharmonic relationships, equivalent to freq / n.

Parameters

n	The subharmonic divisor (must be positive).

Returns: A frequency representing the nth subharmonic.

Definition at line 536 of file frequency.hpp.

References freq::frequency_cast().

◆ wavelength() [1/2]

template<typename Rep , typename Precision >

template<distance_like Distance, duration_like Duration>

constexpr Distance freq::frequency< Rep, Precision >::wavelength ( const Duration & time_per_unit_distance ) const

inlineconstexpr

Calculates the wavelength for this frequency.

Returns the wavelength for this frequency given the time it takes for a wave to travel one unit of distance. The relationship is: wavelength = period / time_per_unit_distance

For electromagnetic waves in vacuum, use std::chrono::nanoseconds(3) for approximately 1 nanosecond per 0.3 meters (since light travels ~0.3 meters per nanosecond).

Template Parameters

Distance	The target distance type. Must satisfy the distance_like concept.
Duration	The duration type representing time per unit distance. Must satisfy duration_like.

Parameters

time_per_unit_distance The time it takes to travel one unit of the target distance.

Returns: The wavelength as a distance-like value.

Note: This method uses the period() method internally and performs ratio arithmetic to convert between time and distance domains.

Definition at line 658 of file frequency.hpp.

References freq::frequency_cast().

◆ wavelength() [2/2]

template<typename Rep , typename Precision >

template<distance_like Distance>

constexpr Distance freq::frequency< Rep, Precision >::wavelength ( double velocity = 299792458.0 ) const

inlineconstexpr

Calculates the wavelength for this frequency given a propagation velocity.

Returns the wavelength for this frequency given the propagation velocity. The relationship is: wavelength = velocity / frequency

Template Parameters

Distance The target distance type. Must satisfy the distance_like concept.

Parameters

velocity The propagation velocity in meters per second. Defaults to the speed of light (299,792,458 m/s).

Returns: The wavelength as a distance-like value.

Note: For electromagnetic waves in vacuum, use the default speed of light. For other media or wave types, specify the appropriate propagation velocity. For sound in air at 20°C, use approximately 343 m/s.

Definition at line 710 of file frequency.hpp.

References freq::frequency_cast().

◆ zero()

template<typename Rep , typename Precision >

static constexpr frequency freq::frequency< Rep, Precision >::zero ( )

inlinestaticconstexprnoexcept

Returns a zero frequency.

Definition at line 402 of file frequency.hpp.

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

Referenced by freq::abs().

The documentation for this class was generated from the following file:

frequency/frequency.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Basic Examples

Floating-Point Examples

Member Typedef Documentation

◆ precision

◆ rep

Constructor & Destructor Documentation

◆ frequency() [1/5]

◆ frequency() [2/5]

◆ frequency() [3/5]

◆ frequency() [4/5]

◆ frequency() [5/5]

◆ ~frequency()

Member Function Documentation

◆ count()

◆ harmonic()

◆ max()

◆ min()

◆ octave_shift()

◆ octaves_from()

◆ operator%=() [1/2]

◆ operator%=() [2/2]

◆ operator*=()

◆ operator+()

◆ operator++() [1/2]

◆ operator++() [2/2]

◆ operator+=()

◆ operator-()

◆ operator--() [1/2]

◆ operator--() [2/2]

◆ operator-=()

◆ operator/=()

◆ operator=()

◆ period()

◆ semitone_shift()

◆ semitones_from()

◆ subharmonic()

◆ wavelength() [1/2]

◆ wavelength() [2/2]

◆ zero()