A data type template which represents a dimensioned quantity as a multiple of a precision level, where the dimensions are supplied by a units template parameter and the precision level is specified using a value of type scale. More...

#include <quantity.h>

Inherits sydevs::quantity_base.

Public Member Functions
constexpr	quantity ()
	Constructs an invalid `quantity` value. More...

constexpr	quantity (int64 multiplier)
	Constructs a `quantity` value representing the specified number of units with no prefix (i.e. milli, kilo). More...

constexpr	quantity (int64 multiplier, scale precision)
	Constructs a `quantity` value representing the specified multiple of the specified precision level. More...

constexpr	quantity (const quantity &)=default
	Copy constructor. More...

quantity &	operator= (const quantity &)=default
	Copy assignment. More...

	quantity (quantity &&)=default
	Move constructor. More...

quantity &	operator= (quantity &&)=default
	Move assignment. More...

	~quantity ()=default
	Destructor. More...

constexpr const quantity	fixed_at (scale precision) const
	Returns a new `quantity` value with the length precision changed and fixed. More...

constexpr const quantity	rescaled (scale precision) const
	Returns a new `quantity` value with the length precision changed but neither fixed nor unfixed. More...

constexpr const quantity	refined () const
	Returns a new `quantity` value with the length precision minimized without losing precision. More...

constexpr const quantity	coarsened () const
	Returns a new `quantity` value with the length precision maximized without losing precision. More...

constexpr const quantity	unfixed () const
	Returns a new `quantity` value with the length precision unfixed. More...

quantity &	operator+= (quantity rhs)
	Adds `rhs` to the `quantity` value. More...

quantity &	operator-= (quantity rhs)
	Subtracts `rhs` from the `quantity` value. More...

quantity &	operator*= (float64 rhs)
	Multiplies the `quantity` value by `rhs`. More...

quantity &	operator/= (float64 rhs)
	Divides the `quantity` value by `rhs`. More...

constexpr const quantity	operator+ () const
	Returns a copy of the `quantity` value. More...

constexpr const quantity	operator- () const
	Returns the negation of the `quantity` value. More...

constexpr const quantity	operator+ (quantity rhs) const
	Returns a new `quantity` value with `rhs` added. More...

constexpr const quantity	operator- (quantity rhs) const
	Returns a new `quantity` value with `rhs` subtracted. More...

constexpr const quantity	operator* (float64 rhs) const
	Returns a new `quantity` value multiplied by `rhs`. More...

constexpr const quantity	operator/ (float64 rhs) const
	Returns a new `quantity` value divided by `rhs`. More...

template<typename U_ >
constexpr quantity< decltype(U()*U_())>	operator* (quantity< U_ > rhs) const
	Returns the `quantity` value multiplied by `rhs`. More...

template<typename U_ >
constexpr quantity< decltype(U()/U_())>	operator/ (quantity< U_ > rhs) const
	Returns the `quantity` value divided by `rhs`. More...

template<typename U_ >
constexpr quantity< decltype(U()*U_())>	operator* (U_ rhs) const
	Returns the `quantity` value multiplied by `rhs`. More...

template<typename U_ >
constexpr quantity< decltype(U()/U_())>	operator/ (U_ rhs) const
	Returns the `quantity` value divided by `rhs`. More...

constexpr bool	operator== (quantity rhs) const
	Returns `true` if the `quantity` value equals `rhs`. More...

constexpr bool	operator!= (quantity rhs) const
	Returns `true` if the `quantity` value does not equal `rhs`. More...

constexpr bool	operator< (quantity rhs) const
	Returns `true` if the `quantity` value is less than `rhs`. More...

constexpr bool	operator> (quantity rhs) const
	Returns `true` if the `quantity` value is greater than `rhs`. More...

constexpr bool	operator<= (quantity rhs) const
	Returns `true` if the `quantity` value is at most `rhs`. More...

constexpr bool	operator>= (quantity rhs) const
	Returns `true` if the `quantity` value is at least `rhs`. More...

Public Member Functions inherited from sydevs::quantity_base
constexpr bool	valid () const
	Returns `true` if the `quantity` value is valid. More...

constexpr bool	finite () const
	Returns `true` if the `quantity` value is finite. More...

constexpr int64	multiplier () const
	Returns the number that multiples the length precision. More...

constexpr scale	precision () const
	Returns the length precision. More...

constexpr bool	fixed () const
	Returns `true` if the `quantity` value has a fixed length precision. More...

Static Public Member Functions
static constexpr quantity	inf ()

static constexpr quantity	max (scale precision)

Friends
template<typename U_ >
class	quantity

Additional Inherited Members
Protected Member Functions inherited from sydevs::quantity_base
constexpr	quantity_base ()

constexpr	quantity_base (int64 multiplier)

constexpr	quantity_base (int64 multiplier, scale precision)

constexpr	quantity_base (int64 multiplier, scale precision, bool fixed)

constexpr	quantity_base (scale precision, float64 multiplier, int8 fixed)

constexpr	quantity_base (const quantity_base &)=default
	Copy constructor. More...

quantity_base &	operator= (const quantity_base &)=default
	Copy assignment. More...

	quantity_base (quantity_base &&)=default
	Move constructor. More...

quantity_base &	operator= (quantity_base &&)=default
	Move assignment. More...

	~quantity_base ()=default
	Destructor. More...

Static Protected Member Functions inherited from sydevs::quantity_base
static constexpr int64	constexpr_abs (int64 n)

static constexpr float64	constexpr_abs (float64 x)

static constexpr float64	convert_multiplier (int64 multiplier)

static constexpr int64	convert_level (int64 multiplier, int64 level)

static constexpr float64	offset_multiplier (float64 multiplier)

static constexpr int64	truncate_multiplier (float64 multiplier)

static constexpr int64	round_multiplier (float64 multiplier)

static constexpr int64	scale_multiplier (float64 multiplier, float64 factor)

Protected Attributes inherited from sydevs::quantity_base
float64	multiplier_

scale	precision_

int8	fixed_

Static Protected Attributes inherited from sydevs::quantity_base
static constexpr float64	inf_float64 = std::numeric_limits<float64>::infinity()

static constexpr float64	nan_float64 = std::numeric_limits<float64>::quiet_NaN()

static constexpr int64	inf_int64 = std::numeric_limits<int64>::max()

static constexpr int64	nan_int64 = std::numeric_limits<int64>::min()

Detailed Description

template<typename U>
class sydevs::quantity

A data type template which represents a dimensioned quantity as a multiple of a precision level, where the dimensions are supplied by a units template parameter and the precision level is specified using a value of type scale.

A quantity value allows for the exact specification, addition, and subtraction of dimensioned quantities provided that the following conditions are met:

Quantities can be represented as an integer multiple of a precision level.
The "multiplier", the number which multiplies the precision, is less than 1,000,000,000,000,000 in magnitude (negative quantities are permitted).

A set of constexpr user-defined literals provide a means to construct quantity values, as shown below.

5_m      // 5 meters
5_fs     // 5 femtoseconds
5_um     // 5 micrometers
6_kg     // 6 kilograms
6000_Mg  // 6000 Megagrams

These user-defined literals correspond with the 7 Standard International (SI) base units as represented by units (_g, _m, _s, _A, _K, _mol, _cd), and may also incorporate an SI prefix (y, z, a, f, n, p, u, m, k, M, G, T, P, E, Z, Y). Note one difference from the SI standard: the gram (1_g) is used as the base unit for mass, instead of the kilogram (1_kg) as in the standard.

There are also 4 additional user-defined literals that produce duration-valued quantities with a precision of 1 second and a multiplier scaled up by 60 (?_min), 60*60 (?_hr), 24*60*60 (?_day) or 365*24*60*60 (?_yr). Examples of these literals are below.

5_min // 300 seconds (5 minutes)

7_day // 604,800 seconds (1 week)

Quantity values can also be created by directly invoking one of the three constructors: the default constructor producing an invalid quanitity, the single-argument constructor producing a quantity with a precision of one base unit, and the two-argument constructor where both the multiplier and precision level are supplied.

quantity<grams>()                         // invalid mass quantity
quantity<grams>(3)                        // 3 grams
quantity<meters>(3)                       // 3 meters
quantity<seconds>(3, nano)                // 3 nanoseconds
quantity<decltype(_m/_s)>(3)              // 3 meters/second
quantity<decltype(_g*_m/_s/_s)>(3, kilo)  // 3 Newtons

Type aliases are provided for quantities of the 7 SI base units.

mass                       // quantity<grams>
distance                   // quantity<meters>
duration                   // quantity<seconds>
electric_current           // quantity<amperes>
thermodynamic_temperature  // quantity<kelvins>
amount_of_substance        // quantity<moles>
luminous_intensity         // quantity<candelas>

These can be used in place of quantity<...> for quantities based on SI base units.

mass()             // invalid mass quantity
mass(3)            // 3 grams
distance(3)        // 3 meters
duration(3, nano)  // 3 nanoseconds

One way to construct quantities based on SI derived units is to multiply or divide a quantity value on the left with a units value on the right.

-777_kg*_m/_s/_s // -777 Newtons

90_km/_hr // 25 meters per second (90 kilometers per hour)

Also, multiplying or dividing quantities yields a new quantity with different units.

200_m/8_s // 25 meters per second

To remove the units from a quantity, simply divide by the unit. The result is a dimensionless quantity value (quantity<no_units>) that can be coerced into a floating-point number.

1500_mA/_A // 1.5

One can construct infinite quantities, as well as the maximum representable quantity at a given precision level.

duration::inf() // Infinite duration

mass::max(yocto) // Maximum mass at ys precision (999999999999999_yg)

Precision is a core aspect of quantity types. To illustrate, although (7000_us == 7_ms) evaluates to true, the two values are different. The left-hand side is stored as a muliplier of 7000 and a time precision of microseconds, whereas the right-hand side is stored as a multiplier of 7 and a time precision of milliseconds.

By default, quantity values resulting from arithmetic operations have their precision levels automatically adjusted to minimize rounding error. This default behaviour treats quantity values as base-1000 floating-point numbers. The following examples all involve time values.

3_s + 475_ms       // Result: 3475 milliseconds
1_ks + 1_us        // Result: 1000000001 microseconds
500_ps - 1_ns      // Result: -500 picoseconds
(1.0/3.0)*1_s      // Result: 333333333333333 femtoseconds
(1.0/3.0)*1000_ms  // Result: 333333333333333 femtoseconds
1000_ms/3.0        // Result: 333333333333333 femtoseconds
10_ms/250_us       // Result: 40.0

However, using the fixed_at member function, one can produce quantities with fixed precision levels that remain unchanged through operations, as illustrated below. This is in contrast to the rescaled member function, which neither fixes nor unfixes the precision level.

(1_min + 40_s).fixed_at(micro)/8.0  // Result: 12500000 microseconds
(1_min + 40_s).fixed_at(milli)/8.0  // Result: 12500 milliseconds
(1_min + 40_s).fixed_at(unit)/8.0   // Result: 13 seconds
(1_min + 40_s).rescaled(micro)/8.0  // Result: 12500000 microseconds
(1_min + 40_s).rescaled(milli)/8.0  // Result: 12500 milliseconds
(1_min + 40_s).rescaled(unit)/8.0   // Result: 12500 milliseconds

Fixing the precision level prevents round-off errors when adding or subtracting quantities. On the other hand, precision may be lost as in the above example where 12500 milliseconds is rounded to 13 seconds.

Operations between quantity values fixed at different precision levels result in invalid quantities.

((1_s).fixed_at(milli) + (1_s).fixed_at(micro)).valid() // Result: false

However if two quantity values have different precision levels but only one is fixed, then the fixed precision will be adopted by the result.

((1_s).fixed_at(micro) + (1_s).rescaled(nano)).precision() // Result: micro

A quantity value can be modified using the +=, -=, *=, /= operators. One must be aware that the member functions fixed_at, rescaled, refined, coarsened, and unfixed return new quantity values but leave the original unchanged.

A quantity value may be output or converted to a string using the operator<< overload.

Constructor & Destructor Documentation

template<typename U >

constexpr sydevs::quantity::quantity ( )

Constructs an invalid quantity value.

template<typename U >

constexpr sydevs::quantity::quantity ( int64 multiplier )

explicit

Constructs a quantity value representing the specified number of units with no prefix (i.e. milli, kilo).

The constructed quantity value has the specified multiplier and a precision level of unit. The precision does not remain fixed through operations.

Parameters

multiplier The number that mulitplies the default precision level to yield the represented quantity.

template<typename U >

constexpr sydevs::quantity< U >::quantity	(	int64	multiplier,
		scale	precision
	)

Constructs a quantity value representing the specified multiple of the specified precision level.

The constructed quantity value has the specified multiplier and precision. The precision does not remain fixed through operations.

Parameters

multiplier	The number that mulitplies the specified precision level to yield the represented quantity.
precision	The precision level that is multiplied to yield the represented quantity.

template<typename U>

constexpr sydevs::quantity::quantity ( const quantity & )

default

Copy constructor.

template<typename U>

sydevs::quantity::quantity ( quantity && )

default

Move constructor.

template<typename U>

sydevs::quantity::~quantity ( )

default

Destructor.

Member Function Documentation

template<typename U >

constexpr const quantity sydevs::quantity::coarsened ( ) const

Returns a new quantity value with the length precision maximized without losing precision.

template<typename U >

constexpr const quantity sydevs::quantity::fixed_at ( scale precision ) const

Returns a new quantity value with the length precision changed and fixed.

template<typename U >

constexpr quantity sydevs::quantity::inf ( )

static

template<typename U >

constexpr quantity sydevs::quantity::max ( scale precision )

static

template<typename U >

constexpr bool sydevs::quantity::operator!= ( quantity rhs ) const

Returns true if the quantity value does not equal rhs.

template<typename U >

constexpr const quantity sydevs::quantity::operator* ( float64 rhs ) const

Returns a new quantity value multiplied by rhs.

template<typename U >

template<typename U_ >

constexpr quantity< decltype(U()*U_())> sydevs::quantity::operator* ( quantity< U_ > rhs ) const

Returns the quantity value multiplied by rhs.

template<typename U >

template<typename U_ >

constexpr quantity< decltype(U()*U_())> sydevs::quantity::operator* ( U_ rhs ) const

Returns the quantity value multiplied by rhs.

template<typename U >

quantity & sydevs::quantity::operator*= ( float64 rhs )

Multiplies the quantity value by rhs.

template<typename U >

constexpr const quantity sydevs::quantity::operator+ ( ) const

Returns a copy of the quantity value.

template<typename U >

constexpr const quantity sydevs::quantity::operator+ ( quantity rhs ) const

Returns a new quantity value with rhs added.

template<typename U >

quantity & sydevs::quantity::operator+= ( quantity rhs )

Adds rhs to the quantity value.

template<typename U >

constexpr const quantity sydevs::quantity::operator- ( ) const

Returns the negation of the quantity value.

template<typename U >

constexpr const quantity sydevs::quantity::operator- ( quantity rhs ) const

Returns a new quantity value with rhs subtracted.

template<typename U >

quantity & sydevs::quantity::operator-= ( quantity rhs )

Subtracts rhs from the quantity value.

template<typename U >

constexpr const quantity sydevs::quantity::operator/ ( float64 rhs ) const

Returns a new quantity value divided by rhs.

template<typename U >

template<typename U_ >

constexpr quantity< decltype(U()/U_())> sydevs::quantity::operator/ ( quantity< U_ > rhs ) const

Returns the quantity value divided by rhs.

template<typename U >

template<typename U_ >

constexpr quantity< decltype(U()/U_())> sydevs::quantity::operator/ ( U_ rhs ) const

Returns the quantity value divided by rhs.

template<typename U >

quantity & sydevs::quantity::operator/= ( float64 rhs )

Divides the quantity value by rhs.

template<typename U >

constexpr bool sydevs::quantity::operator< ( quantity rhs ) const

Returns true if the quantity value is less than rhs.

template<typename U >

constexpr bool sydevs::quantity::operator<= ( quantity rhs ) const

Returns true if the quantity value is at most rhs.

template<typename U>

quantity& sydevs::quantity::operator= ( const quantity & )

default

Copy assignment.

template<typename U>

quantity& sydevs::quantity::operator= ( quantity && )

default

Move assignment.

template<typename U >

constexpr bool sydevs::quantity::operator== ( quantity rhs ) const

Returns true if the quantity value equals rhs.

template<typename U >

constexpr bool sydevs::quantity::operator> ( quantity rhs ) const

Returns true if the quantity value is greater than rhs.

template<typename U >

constexpr bool sydevs::quantity::operator>= ( quantity rhs ) const

Returns true if the quantity value is at least rhs.

template<typename U >

constexpr const quantity sydevs::quantity::refined ( ) const

Returns a new quantity value with the length precision minimized without losing precision.

template<typename U >

constexpr const quantity sydevs::quantity::rescaled ( scale precision ) const

Returns a new quantity value with the length precision changed but neither fixed nor unfixed.

template<typename U >

constexpr const quantity sydevs::quantity::unfixed ( ) const

Returns a new quantity value with the length precision unfixed.

Friends And Related Function Documentation

template<typename U>

template<typename U_ >

friend class quantity

friend

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

src/sydevs/core/quantity.h

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

template<typename U> class sydevs::quantity< U >

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

template<typename U>
class sydevs::quantity< U >