biozic / Quantities

About quantities

The purpose of this small library is to perform automatic compile-time or run-time dimensional checking when dealing with quantities and units.

There is no actual distinction between units and quantities, so there are no distinct quantity and unit types. All operations are actually done on quantities. For example, meter is both the unit meter and the quantity 1m. New quantities can be derived from other ones using operators or dedicated functions.

Quantities can be parsed from strings at run time and compile time.

The main SI units and prefixes are predefined. Units with other dimensions can be defined by the user. With a bit of work, a whole system of new units could be defined to use for calculations and parsing.

Copyright 2013-2018, Nicolas Sicard.

License: Boost License 1.0.

Online documentation

Check online documentation here.

Design rationale

Quantities at compile time

1. The library defines a Quantity type (a template) that represents a physical quantity, or any user-defined type of quantity. A quantity can be seen as the product of a scalar value and a vector of dimensions. The vector of dimensions is known at compile time and is part of the type.

2. A Quantity is a wrapper struct around a numeric value, where the only payload is this numeric value; no other data is stored. So the memory size of a quantity is the same as its underlying numeric type. With optimizations on, the compiler generates the same code as if normal numeric values were used.

   For the moment, only built-in numeric types are handled. But it should be possible to make it work with any "number-like" type.

3. Two quantities with the same dimensions share the same type (assuming the underlying numeric types are the same). Thus functions and types using quantities generally won't have to be templated if the dimensions of the quantities are known at compile time.

4. All operations on Quantity values are statically checked for dimensional consistency. If a constuction, an assignment, a calculation (using overloaded operators or special functions) or parsing from string at compile-time is not dimensionnaly consistent, there's a compilation error. Most notably, calculations involving plain built-in numeric types (double, int, etc.) only work with quantities with no dimensions.

   Some operations (construction, assignment, value function, parsing from a run-time string) can use a QVariant argument. In this case, the checks are done at run-time.

Quantities at run time

1. Since it is not always possible, nor sometimes desirable, to know the dimensions of quantities at compile time, the library defines a QVariant type, for which the vector of dimensions is not part of the type, but stored as a member along the numeric value.

2. Calculations and dimensionnal checks are done at run time. Both QVariant and Quantity can be used in the same expressions to a certain extent.

3. All quantities stored as QVariant share the same type, event if the dimensions of the quantities are different.

4. Only calculations that break dimensional consitencies are checked an throw a DimensionException. A QVariant can be reassigned a new quantity with other dimensions.

Consequences of the design

1. The main consequence of principles #3 is that all quantities sharing the same dimensions are internally expressed in the same unit, which is the base unit for this quantity. For instance, all lengths are stored as meters, which is the base unit of length. The quantity 3 km is stored as 3000 m, 2 min is stored as 120 s, etc.

   The drawback (possibly an important one) is that, when assigning a new value to a quantity, the binary representation is preserved only if the quantity is expressed in the base unit.

2. An indirect consequence is that there is no unit symbol stored with a quantity. The only relevant symbol would have been the one of the base unit, but it's rarely the best choice.

   But in practice, when formatting a quantity, the unit is usually chosen in advance. If not, no simple algorithm is capable of guessing the relevant unit. So I have decided that a quantity wouldn't format itself correctly. Instead, for now, the toString function prints the value and the dimensions vector.

   To print the units properly, the user can use the siFormat functions (obviously, they work only for SI units at the moment), or use the result of the value method.

Examples

Synopsis at compile-time

import quantities.compiletime;
import quantities.si;

// Define a quantity from SI units
auto distance = 384_400 * kilo(meter);

// Define a quantity from a string
auto speed = si!"299_792_458 m/s";
// Define a type for a quantity
alias Speed = typeof(speed);

// Calculations on quantities
auto calculateTime(Length d, Speed s)
{
    return d / s;
}
Time time = calculateTime(distance, speed);

// Dimensions are checked at compile time for consistency
static assert(!__traits(compiles, distance + speed));

// Format a quantity with a format specification known at compile-time
assert(siFormat!"%.3f s"(time) == "1.282 s");

Synopsis at run-time

import quantities.runtime;
import quantities.si;
import std.exception : assertThrown;

// Define a quantity from SI units (using the helper function `qVariant`)
auto distance = qVariant(384_400 * kilo(meter));

// Define a quantity from a string
auto speed = parseSI("299_792_458 m/s");

// Calculations on quantities (checked at compile time for consistency)
QVariant!double calculateTime(QVariant!double d, QVariant!double s)
{
    return d / s;
}
auto time = calculateTime(distance, speed);

// Dimensions are checked at run time for consistency
assertThrown!DimensionException(distance + speed);

// Format a quantity with a format specification known at run-time
assert(siFormat("%.3f s", time) == "1.282 s");

See more complete examples at run time and at compile time.