SyDEVS  v0.6.5
Multiscale Simulation and Systems Modeling Library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
sydevs::quantity< U > Class Template Reference

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...
 
quantityoperator= (const quantity &)=default
 Copy assignment. More...
 
 quantity (quantity &&)=default
 Move constructor. More...
 
quantityoperator= (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...
 
quantityoperator+= (quantity rhs)
 Adds rhs to the quantity value. More...
 
quantityoperator-= (quantity rhs)
 Subtracts rhs from the quantity value. More...
 
quantityoperator*= (float64 rhs)
 Multiplies the quantity value by rhs. More...
 
quantityoperator/= (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_baseoperator= (const quantity_base &)=default
 Copy assignment. More...
 
 quantity_base (quantity_base &&)=default
 Move constructor. More...
 
quantity_baseoperator= (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< U >

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< U >::quantity ( )

Constructs an invalid quantity value.

template<typename U >
constexpr sydevs::quantity< U >::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
multiplierThe 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
multiplierThe number that mulitplies the specified precision level to yield the represented quantity.
precisionThe precision level that is multiplied to yield the represented quantity.
template<typename U>
constexpr sydevs::quantity< U >::quantity ( const quantity< U > &  )
default

Copy constructor.

template<typename U>
sydevs::quantity< U >::quantity ( quantity< U > &&  )
default

Move constructor.

template<typename U>
sydevs::quantity< U >::~quantity ( )
default

Destructor.

Member Function Documentation

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::coarsened ( ) const

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

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::fixed_at ( scale  precision) const

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

template<typename U >
constexpr quantity< U > sydevs::quantity< U >::inf ( )
static
template<typename U >
constexpr quantity< U > sydevs::quantity< U >::max ( scale  precision)
static
template<typename U >
constexpr bool sydevs::quantity< U >::operator!= ( quantity< U >  rhs) const

Returns true if the quantity value does not equal rhs.

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::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< U >::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< U >::operator* ( U_  rhs) const

Returns the quantity value multiplied by rhs.

template<typename U >
quantity< U > & sydevs::quantity< U >::operator*= ( float64  rhs)

Multiplies the quantity value by rhs.

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::operator+ ( ) const

Returns a copy of the quantity value.

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::operator+ ( quantity< U >  rhs) const

Returns a new quantity value with rhs added.

template<typename U >
quantity< U > & sydevs::quantity< U >::operator+= ( quantity< U >  rhs)

Adds rhs to the quantity value.

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::operator- ( ) const

Returns the negation of the quantity value.

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::operator- ( quantity< U >  rhs) const

Returns a new quantity value with rhs subtracted.

template<typename U >
quantity< U > & sydevs::quantity< U >::operator-= ( quantity< U >  rhs)

Subtracts rhs from the quantity value.

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::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< U >::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< U >::operator/ ( U_  rhs) const

Returns the quantity value divided by rhs.

template<typename U >
quantity< U > & sydevs::quantity< U >::operator/= ( float64  rhs)

Divides the quantity value by rhs.

template<typename U >
constexpr bool sydevs::quantity< U >::operator< ( quantity< U >  rhs) const

Returns true if the quantity value is less than rhs.

template<typename U >
constexpr bool sydevs::quantity< U >::operator<= ( quantity< U >  rhs) const

Returns true if the quantity value is at most rhs.

template<typename U>
quantity& sydevs::quantity< U >::operator= ( const quantity< U > &  )
default

Copy assignment.

template<typename U>
quantity& sydevs::quantity< U >::operator= ( quantity< U > &&  )
default

Move assignment.

template<typename U >
constexpr bool sydevs::quantity< U >::operator== ( quantity< U >  rhs) const

Returns true if the quantity value equals rhs.

template<typename U >
constexpr bool sydevs::quantity< U >::operator> ( quantity< U >  rhs) const

Returns true if the quantity value is greater than rhs.

template<typename U >
constexpr bool sydevs::quantity< U >::operator>= ( quantity< U >  rhs) const

Returns true if the quantity value is at least rhs.

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::refined ( ) const

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

template<typename U >
constexpr const quantity< U > sydevs::quantity< U >::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< U > sydevs::quantity< U >::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: