Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Memory and Utilities

C++ std::ratio class template

Reference for std::ratio: compile-time rational numbers, ratio_add and friends, SI prefixes like std::milli, and how chrono uses them for durations.

std::ratio<Num, Den> (header <ratio>) is a type that represents an exact fraction, known at compile time. The numerator and denominator are template arguments, and the fraction is always reduced to lowest terms, with the sign carried by the numerator. A ratio has no objects of interest; you read its two static members, num and den.

Its main customer is std::chrono: a duration's tick period is a std::ratio giving the length of one tick in seconds. The header also defines the metric prefixes std::kilo, std::milli, std::micro and others, plus compile-time arithmetic and comparison.

C++
using third = std::ratio<2, 6>;   // reduced to 1/3
static_assert(third::num == 1 && third::den == 3);

Try it

C++ Reduction and arithmetic

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Metric prefixes and chrono

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
template<std::intmax_t Num, std::intmax_t Den = 1> class ratio;

template<class R1, class R2> using ratio_add      = /* ratio */;
template<class R1, class R2> using ratio_subtract = /* ratio */;
template<class R1, class R2> using ratio_multiply = /* ratio */;
template<class R1, class R2> using ratio_divide   = /* ratio */;
template<class R1, class R2> struct ratio_equal;   // also _not_equal, _less, _less_equal, _greater, _greater_equal
Name Description
Num Numerator, a compile-time std::intmax_t.
Den Denominator, non-zero. Defaults to 1.
R1, R2 Instances of std::ratio used by the arithmetic and comparison templates.

Members: type (the reduced ratio itself), num, den.

Results: the arithmetic aliases name a new, reduced ratio. The comparison templates derive from std::bool_constant; use std::ratio_less_v<R1, R2> style variables for the value.

Errors: a zero denominator, or any numerator, denominator or intermediate result that does not fit in std::intmax_t, is a compile error rather than a runtime overflow.

Usage notes

  • Everything is reduced: ratio<2, 6>::num is 1, ratio<2, 6>::den is 3. ratio<2, 6> and ratio<1, 3> are different types, but ratio<2, 6>::type is ratio<1, 3>.
  • Prefix aliases: atto, femto, pico, nano, micro, milli, centi, deci, deca, hecto, kilo, mega, giga, tera, peta, exa. The extreme prefixes (yocto, zepto, zetta, yotta and the newer ronto to quetta) need a wider intmax_t than the usual 64 bits, so they are normally absent.
  • Use _v variables (C++17) such as std::ratio_equal_v instead of ::value.
  • No floating point. If you need a decimal value, divide at runtime: double(r::num) / r::den.
  • Overflow is caught at compile time, which makes ratio a safe place to scale units.
  • Duration conversions are done with ratio_divide internally; implicit conversions between durations only compile when no precision would be lost.