Fraction template type using integral values, evaluated at runtime. More...

#include <fraction_type.hpp>

Inheritance diagram for jau::fraction< Int_type, >:

Collaboration diagram for jau::fraction< Int_type, >:

Public Types
typedef Int_type	int_type
	User defined integral integer template type, used for numerator and may be signed.

typedef std::make_unsigned_t< int_type >	uint_type
	unsigned variant of template int_type, used for denominator.

Public Member Functions
constexpr	fraction () noexcept
	Constructs a zero fraction instance { 0, 1 }.

template<typename T, std::enable_if_t< std::is_same_v< int_type, T > &&!std::is_unsigned_v< T >, bool > = true>
constexpr	fraction (const int_type &n, const T &d) noexcept
	Constructs a fraction instance with smallest numerator and denominator using gcd()

constexpr	fraction (const int_type &n, const uint_type &abs_d) noexcept
	Constructs a fraction instance with smallest numerator and denominator using gcd()

template<typename Rep, typename Period>
constexpr	fraction (const std::chrono::duration< Rep, Period > &dur) noexcept
	Constructs a fraction from the given std::chrono::duration and its Rep and Period with smallest numerator and denominator using gcd()

constexpr bool	is_zero () const noexcept
	Returns true if numerator is zero.

constexpr fraction< int_type > &	operator*= (const fraction< int_type > &rhs) noexcept
	Multiplication in place.

constexpr fraction< int_type > &	operator*= (const int_type &rhs) noexcept
	Multiplication of this fraction's numerator with scalar in place.

constexpr fraction< int_type > &	operator+= (const fraction< int_type > &rhs) noexcept
	Compound assignment (addition)

constexpr fraction< int_type >	operator- () const noexcept
	Unary minus.

constexpr fraction< int_type > &	operator-= (const fraction< int_type > &rhs) noexcept
	Negative compound assignment (subtraction)

constexpr fraction< int_type > &	operator/= (const fraction< int_type > &rhs) noexcept
	Division in place.

constexpr fraction< int_type > &	operator/= (const int_type &rhs) noexcept
	Division of this fraction's numerator with scalar in place.

constexpr fraction< int_type > &	reduce () noexcept
	Reduce this fraction to the lowest terms using the greatest common denominator, see gcd(), i.e.

constexpr snsize_t	sign () const noexcept
	Returns the value of the sign function applied to numerator.

constexpr double	to_double () const noexcept
	Returns the converted fraction to lossy double.

template<typename Rep, typename Period>
std::chrono::duration< Rep, Period >	to_duration (const std::chrono::duration< Rep, Period > &dur_ref, bool *overflow_ptr=nullptr) const noexcept
	Convert this fraction into std::chrono::duration with given Rep and Period.

constexpr float	to_float () const noexcept
	Returns the converted fraction to lossy float.

constexpr long double	to_ldouble () const noexcept
	Returns the converted fraction to lossy long double.

constexpr int_type	to_ms () const noexcept
	Convenient shortcut to `to_num_of(1_ms)`

constexpr int_type	to_ns () const noexcept
	Convenient shortcut to `to_num_of(1_ns)`

constexpr int_type	to_num_of (const fraction< int_type > &new_base, bool *overflow_ptr=nullptr) const noexcept
	Converts this this fraction to a numerator for the given new base fraction.

constexpr int_type	to_num_of (const int_type &new_base_num, const uint_type &new_base_denom, bool *overflow_ptr=nullptr) const noexcept
	Converts this this fraction to a numerator for the given new base fraction.

constexpr int_type	to_us () const noexcept
	Convenient shortcut to `to_num_of(1_us)`

std::string	toString (const bool show_double=false) const noexcept
	Returns a string representation of this fraction.

Public Attributes
uint_type	denom
	Denominator, always positive.

int_type	num
	Numerator, carries the sign.

bool	overflow
	Overflow flag.

Detailed Description

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>
class jau::fraction< Int_type, >

Fraction template type using integral values, evaluated at runtime.

All operations reduce its fraction to the lowest terms using the greatest common divisor (gcd()) following Euclid's algorithm from Euclid's Elements ~300 BC, see reduce().

fraction provides similar properties like C++11's std::ratio, but is evaluated at runtime time without constexpr constraints using a common integral template type. std::ratio is evaluated at compile time and must use constexpr literal values.

fraction provides similar properties like C++11's std::chrono::duration, but is flexible with its denominator and always reduce() its fraction to the lowest terms. std::chrono::duration uses a fixed std::ratio denominator and hence is inflexible.

Further, fraction can be converted to std::chrono::duration, matching the selected duration's period, see to_duration_count() and to_duration(). However, it is recommended to use fraction_timespec, see below.

The following properties are exposed:

Numerator carries sign and hence can be negative and of signed type
Denominator is always positive and is an unsigned type
All operations incl. construction will result in a reduced fraction using the greatest common denominator, see gcd().
No exceptions are thrown, a zero denominator is undefined behavior (UB), implementation will return zero { n=0, d=1 }.

See usable fixed typedef's

fraction_i64
fraction_ui64

fraction_timespec covers high precision and an almost infinite range of time similar to struct timespec_t.

Counting nanoseconds in int64_t only lasts until 2262-04-12, since INT64_MAX is 9'223'372'036'854'775'807 for 9'223'372'036 seconds or 292 years.

Hence one may use fraction_i64 for durations up to 292 years and fraction_timespec for almost infinite range of time-points or durations beyond 292 years.

Constants are provided in namespace jau::fractions_i64, from fractions_i64::pico to fractions_i64::tera, including fractions_i64::seconds to fractions_i64::years, etc.

Literal operators are provided in namespace jau::fractions_i64_literals, e.g. for 3_s, 100_ns ... literals.

Template Parameters

int_type

Definition at line 106 of file fraction_type.hpp.

Member Typedef Documentation

◆ int_type

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

typedef Int_type jau::fraction< Int_type, >::int_type

User defined integral integer template type, used for numerator and may be signed.

Definition at line 109 of file fraction_type.hpp.

◆ uint_type

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

typedef std::make_unsigned_t<int_type> jau::fraction< Int_type, >::uint_type

unsigned variant of template int_type, used for denominator.

Definition at line 112 of file fraction_type.hpp.

Constructor & Destructor Documentation

◆ fraction() [1/4]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

jau::fraction< Int_type, >::fraction ( )

inlineconstexprnoexcept

Constructs a zero fraction instance { 0, 1 }.

Definition at line 133 of file fraction_type.hpp.

◆ fraction() [2/4]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

template<typename T, std::enable_if_t< std::is_same_v< int_type, T > &&!std::is_unsigned_v< T >, bool > = true>

jau::fraction< Int_type, >::fraction	(	const int_type &	n,
		const T &	d )

inlineconstexprnoexcept

Constructs a fraction instance with smallest numerator and denominator using gcd()

Note: sign is always stored in fraction's numerator, i.e. the denominator is always positive.

Parameters

n	the given numerator
d	the given denominator

Definition at line 148 of file fraction_type.hpp.

◆ fraction() [3/4]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

jau::fraction< Int_type, >::fraction	(	const int_type &	n,
		const uint_type &	abs_d )

inlineconstexprnoexcept

Constructs a fraction instance with smallest numerator and denominator using gcd()

Note: sign is always stored in fraction's numerator, i.e. the denominator is always positive and hence unsigned.

Parameters

n	the given numerator
d	the given denominator

Definition at line 167 of file fraction_type.hpp.

◆ fraction() [4/4]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

template<typename Rep, typename Period>

jau::fraction< Int_type, >::fraction ( const std::chrono::duration< Rep, Period > & dur )

inlineconstexprnoexcept

Constructs a fraction from the given std::chrono::duration and its Rep and Period with smallest numerator and denominator using gcd()

Note: sign is always stored in fraction's numerator, i.e. the denominator is always positive and hence unsigned.

Template Parameters

Rep	Rep of given std::chrono::duration
Period	Period of given std::chrono::duration

Parameters

dur	std::chrono::duration reference to convert into a fraction

Definition at line 318 of file fraction_type.hpp.

Member Function Documentation

◆ reduce()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

fraction< int_type > & jau::fraction< Int_type, >::reduce ( )

inlineconstexprnoexcept

Reduce this fraction to the lowest terms using the greatest common denominator, see gcd(), i.e.

normalization.

Might need to be called after manual modifications on numerator or denominator.

Not required after applying any provided operation as they normalize the fraction.

Definition at line 205 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ to_num_of() [1/2]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

int_type jau::fraction< Int_type, >::to_num_of	(	const fraction< int_type > &	new_base,
		bool *	overflow_ptr = nullptr ) const

inlineconstexprnoexcept

Converts this this fraction to a numerator for the given new base fraction.

If overflow_ptr is not nullptr, true is stored if an overflow occurred otherwise false.

Parameters

new_base	the new base fraction for conversion
overflow_ptr	optional pointer to overflow result, defaults to nullptr

Returns: numerator representing this fraction on the new base, or std::numeric_limits<int_type>::max() if an overflow occurred.

Definition at line 223 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ to_num_of() [2/2]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

int_type jau::fraction< Int_type, >::to_num_of	(	const int_type &	new_base_num,
		const uint_type &	new_base_denom,
		bool *	overflow_ptr = nullptr ) const

inlineconstexprnoexcept

Converts this this fraction to a numerator for the given new base fraction.

If overflow_ptr is not nullptr, true is stored if an overflow occurred otherwise false.

Parameters

new_base_num	the new base numerator for conversion
new_base_denom	the new base denominator for conversion
new_base	the new base fraction for conversion
overflow_ptr	optional pointer to overflow result, defaults to nullptr

Returns: numerator representing this fraction on the new base, or std::numeric_limits<int_type>::max() if an overflow occurred.

Definition at line 257 of file fraction_type.hpp.

◆ to_ms()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

int_type jau::fraction< Int_type, >::to_ms ( ) const

inlineconstexprnoexcept

Convenient shortcut to to_num_of(1_ms)

Returns: time in milliseconds

See also: to_num_of()

Definition at line 282 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ to_us()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

int_type jau::fraction< Int_type, >::to_us ( ) const

inlineconstexprnoexcept

Convenient shortcut to to_num_of(1_us)

Returns: time in microseconds

See also: to_num_of()

Definition at line 289 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ to_ns()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

int_type jau::fraction< Int_type, >::to_ns ( ) const

inlineconstexprnoexcept

Convenient shortcut to to_num_of(1_ns)

Returns: time in nanoseconds

See also: to_num_of()

Definition at line 296 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ to_float()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

float jau::fraction< Int_type, >::to_float ( ) const

inlineconstexprnoexcept

Returns the converted fraction to lossy float.

Definition at line 299 of file fraction_type.hpp.

◆ to_double()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

double jau::fraction< Int_type, >::to_double ( ) const

inlineconstexprnoexcept

Returns the converted fraction to lossy double.

Definition at line 302 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ to_ldouble()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

long double jau::fraction< Int_type, >::to_ldouble ( ) const

inlineconstexprnoexcept

Returns the converted fraction to lossy long double.

Definition at line 305 of file fraction_type.hpp.

◆ to_duration()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

template<typename Rep, typename Period>

std::chrono::duration< Rep, Period > jau::fraction< Int_type, >::to_duration	(	const std::chrono::duration< Rep, Period > &	dur_ref,
		bool *	overflow_ptr = nullptr ) const

inlinenoexcept

Convert this fraction into std::chrono::duration with given Rep and Period.

If overflow_ptr is not nullptr, true is stored if an overflow occurred otherwise false.

Template Parameters

Rep	std::chrono::duration numerator type
Period	std::chrono::duration denominator type, i.e. a std::ratio

Parameters

dur_ref	std::chrono::duration reference to please automated template type deduction and ease usage
overflow_ptr	optional pointer to overflow result, defaults to nullptr

Returns: fraction converted into given std::chrono::duration Rep and Period, or using (Rep)std::numeric_limits<Rep>::max() if an overflow occurred

Definition at line 343 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ toString()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

std::string jau::fraction< Int_type, >::toString ( const bool show_double = false ) const

inlinenoexcept

Returns a string representation of this fraction.

If the overflow flag is set, O! will be appended.

Parameters

show_double true to show the double value, otherwise false (default)

Returns

Definition at line 368 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ is_zero()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

bool jau::fraction< Int_type, >::is_zero ( ) const

inlineconstexprnoexcept

Returns true if numerator is zero.

Definition at line 391 of file fraction_type.hpp.

◆ sign()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

snsize_t jau::fraction< Int_type, >::sign ( ) const

inlineconstexprnoexcept

Returns the value of the sign function applied to numerator.

-1 for numerator < 0
 0 for numerator = 0
 1 for numerator > 0

Returns: function result

Definition at line 404 of file fraction_type.hpp.

◆ operator-()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

fraction< int_type > jau::fraction< Int_type, >::operator- ( ) const

inlineconstexprnoexcept

Unary minus.

Returns: new instance with negated value, reduced

Definition at line 413 of file fraction_type.hpp.

◆ operator*=() [1/2]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

fraction< int_type > & jau::fraction< Int_type, >::operator*= ( const int_type & rhs )

inlineconstexprnoexcept

Multiplication of this fraction's numerator with scalar in place.

Operation may set the overflow flag if occurring.

Parameters

rhs	the scalar

Returns: reference to this instance, reduced

Definition at line 427 of file fraction_type.hpp.

◆ operator/=() [1/2]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

fraction< int_type > & jau::fraction< Int_type, >::operator/= ( const int_type & rhs )

inlineconstexprnoexcept

Division of this fraction's numerator with scalar in place.

Parameters

rhs	the scalar

Returns: reference to this instance, reduced

Definition at line 442 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ operator+=()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

fraction< int_type > & jau::fraction< Int_type, >::operator+= ( const fraction< int_type > & rhs )

inlineconstexprnoexcept

Compound assignment (addition)

Operation may set the overflow flag if occurring.

Parameters

rhs	the other fraction

Returns: reference to this instance, reduced

Definition at line 454 of file fraction_type.hpp.

◆ operator-=()

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

fraction< int_type > & jau::fraction< Int_type, >::operator-= ( const fraction< int_type > & rhs )

inlineconstexprnoexcept

Negative compound assignment (subtraction)

Operation may set the overflow flag if occurring.

Parameters

rhs	the other fraction

Returns: reference to this instance, reduced

Definition at line 479 of file fraction_type.hpp.

◆ operator*=() [2/2]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

fraction< int_type > & jau::fraction< Int_type, >::operator*= ( const fraction< int_type > & rhs )

inlineconstexprnoexcept

Multiplication in place.

Operation may set the overflow flag if occurring.

Parameters

rhs	the other fraction

Returns: reference to this instance, reduced

Definition at line 514 of file fraction_type.hpp.

◆ operator/=() [2/2]

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

fraction< int_type > & jau::fraction< Int_type, >::operator/= ( const fraction< int_type > & rhs )

inlineconstexprnoexcept

Division in place.

Parameters

rhs	the other fraction

Returns: reference to this instance, reduced

Definition at line 534 of file fraction_type.hpp.

Member Data Documentation

◆ num

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

int_type jau::fraction< Int_type, >::num

Numerator, carries the sign.

Definition at line 115 of file fraction_type.hpp.

◆ denom

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

uint_type jau::fraction< Int_type, >::denom

Denominator, always positive.

Definition at line 117 of file fraction_type.hpp.

◆ overflow

template<typename Int_type, std::enable_if_t< std::is_integral_v< Int_type >, bool > = true>

bool jau::fraction< Int_type, >::overflow

Overflow flag.

If set, last arithmetic operation produced an overflow. Must be cleared manually.

Definition at line 119 of file fraction_type.hpp.

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

include/jau/fraction_type.hpp

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ int_type

◆ uint_type

Constructor & Destructor Documentation

◆ fraction() [1/4]

◆ fraction() [2/4]

◆ fraction() [3/4]

◆ fraction() [4/4]

Member Function Documentation

◆ reduce()

◆ to_num_of() [1/2]

◆ to_num_of() [2/2]

◆ to_ms()

◆ to_us()

◆ to_ns()

◆ to_float()

◆ to_double()

◆ to_ldouble()

◆ to_duration()

◆ toString()

◆ is_zero()

◆ sign()

◆ operator-()

◆ operator*=() [1/2]

◆ operator/=() [1/2]

◆ operator+=()

◆ operator-=()

◆ operator*=() [2/2]

◆ operator/=() [2/2]

Member Data Documentation

◆ num

◆ denom

◆ overflow