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

#include <quanta/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> && detail::_lossless_conversion<Rep2, Precision2, rep, precision> && detail::_quantity_castable<frequency<Rep2, Precision2>, frequency>
constexpr	frequency (const frequency< Rep2, Precision2 > &f)
	Constructs from another frequency with different representation or precision.

template<typename Rep2 , typename Precision2 > requires (!detail::_lossless_conversion<Rep2, Precision2, rep, precision> \|\| !std::convertible_to<const Rep2&, rep>) && detail::_quantity_castable<frequency<Rep2, Precision2>, frequency>
constexpr	frequency (const frequency< Rep2, Precision2 > &f)
	Explicit constructor for lossy 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 quanta::frequency::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 222 of file frequency.hpp.

Member Typedef Documentation

◆ precision

template<typename Rep , typename Precision >

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

The precision as a std::ratio.

Definition at line 231 of file frequency.hpp.

◆ rep

template<typename Rep , typename Precision >

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

The representation type.

Definition at line 229 of file frequency.hpp.

Constructor & Destructor Documentation

◆ frequency() [1/5]

template<typename Rep , typename Precision >

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

constexprdefault

Constructs a zero frequency.

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

◆ frequency() [2/5]

template<typename Rep , typename Precision >

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

◆ frequency() [4/5]

template<typename Rep , typename Precision >

template<typename Rep2 , typename Precision2 >
requires std::convertible_to<const Rep2&, rep> && detail::_lossless_conversion<Rep2, Precision2, rep, precision> && detail::_quantity_castable<frequency<Rep2, Precision2>, frequency>

constexpr quanta::frequency::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 (the target rep is floating-point, or the target precision evenly divides the source precision and the source rep is not floating-point) and the source rep converts implicitly to the target rep. Any other conversion that the cast can perform is explicit (see below).

Template Parameters

Rep2	Source representation type.
Precision2	Source precision.

Parameters

f	The source frequency.

Definition at line 268 of file frequency.hpp.

◆ frequency() [5/5]

template<typename Rep , typename Precision >

template<typename Rep2 , typename Precision2 >
requires (!detail::_lossless_conversion<Rep2, Precision2, rep, precision> || !std::convertible_to<const Rep2&, rep>) && detail::_quantity_castable<frequency<Rep2, Precision2>, frequency>

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

inlineexplicitconstexpr

Explicit constructor for lossy conversions.

Every conversion that the cast can perform and that is not implicit (see above) is explicit: a lossy one (to a coarser precision, or from a floating-point rep to an integral one), or one to a rep that the source rep converts to only explicitly. The value is that of the domain's cast, truncated toward zero. The cast can perform the conversion when the conversion factor between the precisions fits in a std::ratio and the reps are integral or have a common type with intmax_t through which the count converts.

Template Parameters

Rep2	Source representation type.
Precision2	Source precision.

Parameters

f	The source frequency.

Definition at line 291 of file frequency.hpp.

◆ ~frequency()

template<typename Rep , typename Precision >

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

default

Member Function Documentation

◆ count()

template<typename Rep , typename Precision >

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

inlineconstexpr

Returns the tick count.

Definition at line 298 of file frequency.hpp.

Referenced by quanta::frequency::frequency< Rep, Precision >::operator%=(), quanta::frequency::frequency< Rep, Precision >::operator+=(), quanta::frequency::frequency< Rep, Precision >::operator-=(), quanta::frequency::operator/(), quanta::frequency::operator<=>(), quanta::frequency::operator==(), quanta::frequency::frequency< Rep, Precision >::period(), and quanta::frequency::to_string().

◆ harmonic()

template<typename Rep , typename Precision >

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

◆ max()

template<typename Rep , typename Precision >

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

inlinestaticconstexprnoexcept

Returns the maximum representable frequency.

Definition at line 363 of file frequency.hpp.

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

◆ min()

template<typename Rep , typename Precision >

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

inlinestaticconstexprnoexcept

Returns the minimum representable frequency.

Definition at line 360 of file frequency.hpp.

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

◆ octave_shift()

template<typename Rep , typename Precision >

template<typename T = double>

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

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

◆ octaves_from()

template<typename Rep , typename Precision >

template<typename T = double>

T quanta::frequency::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 570 of file frequency.hpp.

◆ operator%=() [1/2]

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 349 of file frequency.hpp.

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

◆ operator%=() [2/2]

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 342 of file frequency.hpp.

◆ operator*=()

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 332 of file frequency.hpp.

◆ operator+()

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 300 of file frequency.hpp.

◆ operator++() [1/2]

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 308 of file frequency.hpp.

◆ operator++() [2/2]

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 313 of file frequency.hpp.

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

◆ operator+=()

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 322 of file frequency.hpp.

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

◆ operator-()

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 304 of file frequency.hpp.

◆ operator--() [1/2]

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 315 of file frequency.hpp.

◆ operator--() [2/2]

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 320 of file frequency.hpp.

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

◆ operator-=()

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 327 of file frequency.hpp.

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

◆ operator/=()

template<typename Rep , typename Precision >

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

inlineconstexpr

Definition at line 337 of file frequency.hpp.

◆ operator=()

template<typename Rep , typename Precision >

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

default

◆ period()

template<typename Rep , typename Precision >

template<duration_like Duration>

constexpr Duration quanta::frequency::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, a std::chrono::duration (see duration_like).

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

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

◆ semitone_shift()

template<typename Rep , typename Precision >

template<typename T = double>

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

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

◆ semitones_from()

template<typename Rep , typename Precision >

template<typename T = double>

T quanta::frequency::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 586 of file frequency.hpp.

◆ subharmonic()

template<typename Rep , typename Precision >

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

◆ wavelength() [1/2]

template<typename Rep , typename Precision >

template<distance_like Distance, duration_like Duration>

constexpr Distance quanta::frequency::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, e.g. quanta::spatial::millimeters. Must satisfy the distance_like concept (so it cannot be a std::chrono::duration).
Duration	The duration type representing time per unit distance, a std::chrono::duration.

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

◆ wavelength() [2/2]

template<typename Rep , typename Precision >

template<distance_like Distance>

constexpr Distance quanta::frequency::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, e.g. quanta::spatial::millimeters. Must satisfy the distance_like concept (so it cannot be a std::chrono::duration).

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.

// With quanta::spatial

auto lambda = (2400_MHz).wavelength<quanta::spatial::millimeters>(); // 124 mm

Definition at line 667 of file frequency.hpp.

◆ zero()

template<typename Rep , typename Precision >

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

inlinestaticconstexprnoexcept

Returns a zero frequency.

Definition at line 357 of file frequency.hpp.

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

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

quanta/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()