User Manual

Introduction

This manual describes the Quantities package from a user's perspective. It describes the operations which can be performed on and with Quantities objects during their life cycle.

Using Quantity Objects

Preparing for Use of Quantities

First, make sure that the Quantities package is installed according to the Installation instructions given elsewhere.

In order to use the classes within the Quantities package in your program, you have to (a) include header files in your client code, and (b) link the program against libraries.

For the discussion of header files, we assume that you point your compiler to use the installation directory of Quantities in the search path for header files. For example, with GNU gcc use

-I <_install_directory_>/include/Quantities-<versionnumber>

with <_install_directory_> being the installation directory (e.g., given as the --prefix option during installation of the package) and <versionnumber> being the version number of the Quantities package.

To include specific physical quantity header files, e.g. Time.h, use

 #include "Quantities/PhysicalQuantities/Time.h"

or the respective include directive. In this case, all relevant basic header files are automatically included. This is recommended for user code.

If you want to include only some of the header files, without including any PhysicalQuantities header, use

 #include "Quantities/Quantity/Prefix.h"

 #include "Quantities/Quantity/Unit.h"

 #include "Quantities/Quantity/Dimension.h"

 #include "Quantities/Quantity/Quantity.h"

 #include "Quantities/Quantity/Generic.h"

 #include "Quantities/Quantity/Variable.h"

 #include "Quantities/Quantity/Constant.h"

 #include "Quantities/Quantity/UniqueConstant.h"

to include header file Prefix.h, Unit,h, Dimension.h, Quantity.h, Generic.h, Variable.h, Constant.h, and UniqueConstant.h respectively.

If you do not want to explicitly qualify the namespace for names from the Quantities package, you may include a using directive into your code:

using namespace quantity

If you use special constructs from this library, you might have to include additional using directives to your code:

using namespace BSUtilities
using namespace unit
using namespace dimension

Declarations and definitions for PhysicalQuantities are given in separate namespaces. The name of these namespaces is xxx for PhysicalQuantity Xxx, respectively. The namespace contains the respective Dimension, Units, and Quantity definitions. Of these, user code in most cases will only need the names of the Unit classes. If you do not give a

using namespace xxx

directive (with xxx substituted by the name of the PhysicalQuantity) you have to qualify the scope if you use a unit, e.g.:

Length (1.0, length::Minute);

In the following examples, we will omit these qualifications.

As special case is namespace time. It may conflict with a name in time.h. Thus, to disambiguate, the scope qualifier quantity::time may be needed.

The linker must be instructed to use various libraries in the Quantities package when linking the client program. For GNU gcc, use

-L<_install_directory_>/lib/Quantities-<versionnumber><libtag> -lPhysicalQuantities -lQuantity

Also, you must link your program against the BSUtilities library:

-L<_BSUtilities_install_directory_>/lib/BSUtilities-<versionnumber><libtag> -lBSUtilities

If using a dynamically linked executable, you also have to give the runtime linker enough (and consistent) information about these libraries' place in your file system. Thus, _installdir_/lib/ (and the corresponding path to the BSUtilities library must be present either in ld.so.conf or in LD_LIBRARY_PATH.

The Life Cycle of a Quantity Object

Similar to other objects in a C++ program, the life cycle of a quantity object usually starts with construction. In the special case of a UniqueConstant the corresponding object is constructed only once at the first point of use. After construction the quantity object can be assigned to (if it is a variable quantity) and it can be used in various operations. Finally, the quantity object is destructed.

Construction of Quantity Objects

During the construction of a quantity object, an initial value as well as the name and the symbol of the quantity are determined and stored.

Changes of the value of a variable object during its lifetime is performed mainly through assignment operations. The direct change by supplying a number is not possible. Assignments to (and, thus, value changes of) Constant and UniqueConstant objects are not allowed.

The initial name and symbol of a quantity are determined in the following way: for each base quantity, a default name and symbol is defined. If a derived quantity additionally defines its own name and symbol, and has the Overwrite traits set to true in the DerivedQuantityTraits class, the respective derived values are used. For Variable and Constant objects, the user can override these predefined defaults further by using a special constructor.

Time t;              // value: 0 s, name: time, symbol: t
ElectricCharge Q = ELEMENTARYCHARGE;
                     // the elementary charge uses overwriting values for name and symbol;
                     // name: elementary charge, symbol: e
                     // different from ElectricCharge objects with name: electric charge
                     // and symbol: Q 
Time t (7., "time_seven", "t_7");
                     // value:  7 s, name: time_seven, symbol: t_7

Explicit construction of a quantity object can be done as

an automatic object, e.g.
```
 Time t; // example: default construction, 0 s 
```
which according to C++ rules disappeares when program flow leaves the block of code in which is it created,
on the stack (with operator new), e.g.
```
 Time *t = new Time; // also calls default constructor 
```
In the latter case, the object is persistent. However, the client code has to make sure to explicitly delete the object later when it is no longer needed, in order to avoid memory leaks (see Destruction of Quantity Objects), or
as static quantity objects (except unique constant objects).

A quantity object (except UniqueConstant objects) can be constructed in several ways:

default construction: The default constructor of a quantity object assumes the value 0.0 (for the default storage type double; for other storage types the value which results from conversion of 0 to the type is used). The unit is assumed to be the storage unit of the quantity. Thus, if Time is a time quantity with storage type double and storage unit seconds, the following declaration constructs a variable quantity object with the name t and the value 0.0 s:
```
 Time t;
```
construction with arguments: A quantity object constructor can be called with various combinations of arguments.
1. constructor from value, one argument of storage type:
```
 Time t(5.0); // t = 5.0 s 
```
  This constructs an object with the value given as argument, which is assumed to be in the storage unit of the quantity.
2. constructor from value, one argument of a type which can be converted or promoted by the compiler into the storage type:
```
 Time t(5);        // t = 5.0 s 
```
  This statement constructs a Time object which has storage type double from the int value given as argument. The int value is converted into double.
  Unfortunately, this means that also a character value will be promoted and converted into, e.g. double. The result of this process depends on the character set used. For example:
```
 Time t(`a');        // t = 97 s 
```
  Such constructs should be avoided.
  As with the first construction variant given above, such a statement constructs an object with the value given as argument, which is assumed to be in the storage unit of the quantity.
3. constructor from a value, a name and a symbol string;
```
std::string namestring ("name");
std::string symbolstring ("symbol");
Time t(1.0, namestring, symbolstring);
```
  The name and the symbol can also be given as C string:
```
Time t(1.0, "name", "symbol");
```
4. constructor from value and storage unit, one argument of storage type and second argument being a reference to the storage unit:
```
 Time t(5.0, Second ()); // t = 5 s, as above 
```
  This constructs an object with the value given as argument, which is assumed to be in the unit given as the second argument. In contrast to the previous constructor call, this makes the storage unit explicit.
5. constructor from value and different unit, one argument of storage type and second argument being a reference to an object of any unit of the quantity:
```
 Time t(5.0, Minute ()); // t = 5 min = 300 s 
```
  This constructs an object with the value given as argument, which is assumed to be in the unit given as the second argument and is recalculated into the storager unit. In this construct, the type of the second argument is tested at compile time to make sure that the unit given is a valid unit for the base quantity. Thus,
```
 Time t(5.0, Metre ()); // ERROR  (UnitError<true>)
```
  is invalid code and should be rejected by the compiler. Note, that throughout this document, we denote invalid code by "ERROR". In parentheses, in some cases, a compile time error message fragment is shown.
6. constructor from a value, a unit object and a name and symbol string:
```
Time t (1.0, Minute (), "name", "symbol");
```
  Again, the name and symbol can be given as std::string or C string (as shown here). A unit which is not in the unit list of the quantity is not accepted.
7. constructor from value and a unit symbol given as a character constant, one argument of storage type and second argument being a char *
```
        Time t(5.0, "min"); // t = 5 min = 300 s, as above 
```
  This constructs an object with the value given as argument, which is assumed to be in the unit given as the unit symbol in the second argument. Again, recalculation occurs. In this construct, the type of the second argument can not be tested at compile time. However, at run time, the character constant provided is tested versus the symbols of all available units for the base quantity. If it is not found in the list of these unit symbols, a UnitMismatch exception (Exceptions) is thrown. Thus,
```
 Time t(5.0, "m"); // exception at run time 
```
  would result in such an exception.
8. constructor from value and a unit symbol given as a string, one argument of storage type and second argument being a std::string:
```
        std::string str ("min"); // define string
        Time t(5.0, str); // t = 5 min = 300 s, as above 
```
  This constructor works simular to the previous one with a value and a character constant as argument.
copy construction: a quantity object (target) can be constructed from another quantity object (source) under certain conditions. In all cases the two objects must have the same storage type.
1. copy constructor from same quantity type: this constructor makes an exact copy of the source object.
```
          Time t (1.0); // construction of source
          Time t1 (t);  // copy construction of target, t1 has 
                        // properties identical to t
```
2. copy constructor from quantity related to same base quantity but with different storage unit: this constructor generates an object and recalculates the value of the source object into the unit of the target object. Since both objects are of the same base quantity, it is assured that the recalculation is possible.
```
          MinuteTime t (1.0, Minute ()); // construction, 1 min
          Time t1 (t);             // copy construction, t1 stores 60 s 
```
  This copy constructor acts as a conversion between quantity objects of different type, as long as they are related by the same base quantity.
3. copy constructor from a dynamic quantity object: if some function, e.g. the power function with a dynamic exponent, returns a dynamic quantity object who's dimension can not be determined at compile time, such an object can be used to copy construct a quantity object with commensurable dimension:
```
          Time t (1.9);                 // construction
          int exp = 2;                  // exponent for power function
          SquareTime tsq (pow(t, exp));  // calculate t^2, use dynamic
                                        // return object for copy
                                        // construction
          Time t1 (pow (t, exp));       // DimensionMismatch exception
          SquareMinuteTime tm1 (pow (t, exp));
                                        // calculates t^2, stores in
                                        // unit min^2 after 
                                        // recalculation
```
  Here, SquareTime and SquareMinuteTime are quantity types to store a squared time quantity in s^2 or min^2, respectively.
  Note, that in such a case, a run-time check for commensurability is performed, and no compile-time safety of the code can be guaranteed. A DimensionMismatch exception (Exceptions) is thrown if the dynamic object and the object to be constructed are in commensurable.
4. copy constructor from unnamed transient quantity object: this constructor makes a copy of the source object, but recalculates the value of the source object into the unit of the target object. Generated quantity objects are returned as unnamed transient objects from operators and functions:
```
          Time t (1.0);  // construction
          Time t1 (2.0); // construction
          Time t2 (3.0); // construction
          Time t3 (t * t1 / t2);  // copy construction, t3 stores 2/3 s
```
  In the last line of this example the expression in parentheses returns an unnamed transient quantity object. Commensurability in this case is tested by comparing the dimensions of the generated quantity and the target quantity. As long as the two quantities are commensurable, the client code does not need to care about the resulting conversions.
5. copy constructor from a quantity object of a type not related by the same base quantity: Such a copy construction in general is not allowed within the Quantities package, and yields a link time error:
```
          Time t (1.0);  // construction
          Length l (t);  // ERROR
```
  In special cases, however, some quantity types may define the corresponding conversion. For example, conversion between different types of temperature (ThermodynamicTemperature, CelsiusTemperature, FarenheitTemperature) are allowed:
```
          ThermodynamicTemperature T (298.0);// construction, 298 K
          CelsiusTemperature T1 (T);         // copy construction, 25 oC
```
  Also, an unnamed transient (generated) object, can be copy constructed from any commensurable quantity. However, this should not be used in user code.
Copy construction of both variable and constant quantity objects is possible from a quantity object of any mode. For example, a variable quantity object can be copy constructed from a constant quantity object, and vice versa. Note, that the resulting object will have the mode of the target object, not of the source object. Thus, in the second case mentioned the constructed object will have all properties of a variable, although the source object was a constant:
```
      Time t (1.);         // construction of a variable quantity object
      TimeConstant t1 (t); // t1 is a constant quantity object with
                           // value 1 s. 
```
For object t1 now all restrictions of a constant quantity object apply.

All examples above construct a named object. However, constructors can also be used to generate transient objects, which do not have a name within the client program. Of course, the state of the transient object has to be saved to another (named) object by copy construction or assignment, before it can be used. For example,

 Time t = Time (5.);         // copy construction by unnamed object
                             // t now contains now 5 s
 Time t1 (5.);               // t1 = 5 s; preferred

Since the above code generates a (superfluous) temporary object, and destroys it immediately after copying to t (see also [Dewhurst_2003]), it should possibly be avoided, and direct construction, as for t1 above should be preferred.
Such unnamed transient quantity objects can, however, also be used to print some value (for the use of operator<< see Input and Output Operations with Quantity Objects):

  std::cout << Time (5.) << std::endl; // prints "5 s"

Variable and constant quantity objects can be used after construction in the C++ client code just as built-in types.

Unique constant objects do not need to be constructed explicitly. They are generated at first use. Consequently, you can just write the name of a unique constant in an expression (for assignment in the second line of code in this example, see section Assignment Operations with Quantity Objects):

 AmountOfSubstance m(1., Mole ());        // construction, 1 mol
 ElectricCharge Q = m * FARADAYCONSTANT;  // multiply by F = 96487 C/mol
                                          // and get an ElectricCharge

These two lines first construct an AmountOfSubstance object m, with contents 1 mol. Then, m is multiplied by the Faraday constant to yield an electric charge, in the present case this should be 96487 C.

Conversion Operations between Quantity Objects

... definition of conversion: different storage type, different storage unit; different quantity type only in special cases ...

... conversion by copy construction ...

... conversion by assignment ...

... conversion in special cases ...

... check (copy) construction discussions above !!!!! ...

Assignment Operations with Quantity Objects

With an assignment operation you change the value of an already existing variable quantity object (target) using another object (source).

Of course, constant and unique constant quantity objects can not be target objects (see for one exception for constant objects, below). On the other hand, it is possible to assign to a variable quantity object from a quantity object in any other mode.

The following types of source objects are allowed:

a quantity object of the same type
a quantity object based on the same quantity type, but with possibly different storage type and/or unit
a generated quantity
a Dynamic quantity
a C-style or a std::string see Input Operations with Quantity Objects)
a quantity object based on a different quantity type, if in exceptional cases a specialized form of the assignment operator is provided.

The following types of source objects are prohibited:

a quantity object based on a different quantity type, if not handled by the rules above
any other object, in particular a simple number given in double, int, etc.

There is one strict prerequisite which must be met for assignment: the source and target quantity object must be commensurable. Attempted assignment between incommensurable quantities yields a compile time error.

For example, you can assign time quantities to each other, but not a length to a time:

 Time t1 (1.0);       // construction, value 1 s
 Time t2;             // default construction, value 0 s
 t2 = t1;             // assignment, now t2 has value 1 s
 MinuteTime t3 (1.0); // construction, value 1 min
 t2 = t3;             // assignment, now t2 has value 60 s
 Length l (5.0)       // construction, value 5 m
 t2 = l;              // ERROR, incommensurable quantities

Assignment from an unnamed transient quantity object is possible if the source and the target quantity object are commensurable:

 Time t1 (1.0);      // construction, value 1 s
 Time t2;            // default construction, value 0 s
 t2 = (t1 * t1)/t1;  // value of t2 now 1 s

Assignment to a constant quantity object is only possible within a statement like

 Time t (5.9);            // construction of variable time, 5.9 s
 ConstantTime tc = t;     // copy initialization

Such a statement can be regarded as initialization of the constant quantity object, and symbol = is not an assignment (see Dewhurst [Dewhurst_2003], and the precautions mentioned there).
Assignment can be chained, and it is possible to assign a value in one statement to more than one target:

  Time t1 (25.);    // construction, value 25 s
  Time t2, t3;      // default construction, both objects have value 0 s
  t3 = t2 = t1;     // now all three objects have value 25 s

Assignment from a Dynamic source object is implicitly used when assigning as in

Time t, t1 (1.0), t2 (2.0);
double exp (0.5);
t = pow ((t1 * t2), exp);             // corresponds to sqrt, but non-static exp

where the dimension of the power function result can only be determined at run-time. Note, that in general the dimension of the Dynamic can not be checked at compile-time. Consequently, incommensurable assignments can not be detected before run-time.

Among others, the following assignments are prohibited:

Time t;
t = 5.0;                              // no assignment from double
t = 5;                                // no assignment from int
t = 'a';                              // no assignment from char
BSUtilities::Rational<1,1> r;         // define a Rational<> number
t = r;                                // no assignment from Rational<>

The reason for these restrictions is that a value of a quantity itself is never meaningful. In order to interpret the value always a unit needs to be associated. The user of a quantity object is reminded of that fact when doing an assignment. If it is absolutely necessary to generate a quantity object from only a number, construction should be used.

Mathematical Operations with Quantity Objects

The Quantities package provides mathematical operations with and between quantity objects. Some of these operations concern only a single quantity object and calculate a result from it. Some other operations concern two quantity objects and the result depends on both of them. Note that bitwise operations are not provided for quantity objects.

Mathematical Operations Concerning a Single Quantity Object

Operations on dimensionless quantities: these mathematical operations are restricted to dimensionless quantity objects (i.e., all seven components of the dimension are zero). They can be called on all modes of quantity objects. The numerical result is calculated from the value in the storage unit.

Moreover, as result of these operations a dimensionless generated transient unnamed object is returned, which should be assigned to a full fleged quantity before further use by the user program. It is ok to use the generated transient unnamed object in further arithmetic calculations. For further storage and later reference, however, assign it to a dimensionless quantity, for example PureNumber. Assignment to an object of the storage type is no longer possible in Quantities after version 1.2.1.

For example, if Time and Frequency have storage type double

          Time t (1.0);                         // constructor, 1 s
          Frequency omega (10.0);               // constructor, 10 Hz
          PureNumber t_res0;                    // default construction
          t_res0 = exp (omega * t);             // assignment
          PureNumber t_res1 = log10 (omega * t);  // copy initialization
                                                  // for multiplication,
                                                  // see below, 
                                                  // t_result: 1.0 with unit pureNumber::Unity

A complete list of these functions is given below. It is assumed in the examples that object t1 is dimensionless. Alternatively, it could be an anonymous transient object generated by some arithmetic operations, which is again dimensionless.

operation	example function call	comments
exp	PureNumber t_result = exp (t1);	calculate the exponential of the quantity object value
log	PureNumber t_result = log (t1);	calculate the natural logarithm of the quantity object value
log10	PureNumber t_result = log10 (t1);	calculate the logarithm (base 10) of the quantity object value
sin	PureNumber t_result = sin (t1);	calculate the sine of the quantity object value it is assumed that the value is in rad
cos	PureNumber t_result = cos (t1);	calculate the cosine of the quantity object value it is assumed that the value is in rad
tan	PureNumber t_result = tan (t1);	calculate the tangent of the quantity object value it is assumed that the value is in rad
sinh	PureNumber t_result = sinh (t1);	calculate the hyperbolic sine of the quantity object value it is assumed that the value is in rad
cosh	PureNumber t_result = cosh (t1);	calculate the hyperbolic cosine of the quantity object value it is assumed that the value is in rad
tanh	PureNumber t_result = tanh (t1);	calculate the hyperbolic tangent of the quantity object value it is assumed that the value is in rad
asin	PureNumber t_result = asin (t1);	calculate the arc sine of the quantity object value it is assumed that the value is in rad
acos	PureNumber t_result = acos (t1);	calculate the arc cosine of the quantity object value it is assumed that the value is in rad
atan	PureNumber t_result = atan (t1);	calculate the arc tangent of the quantity object value it is assumed that the value is in rad; for the alternative atan2 function, see below.

Note that the values (as given in the storage unit) of the trigonometric (all of the above, except exp, log and log10) functions' arguments are always interpreted as being in rad. This is similar to the behavior of the C/C++ math.h functions. PlaneAngleQuantities (see below, Plane Angle Quantity and Units) are a special case, since arguments of objects of a type derived from this base quantity recalculate their value automatically into rad before performing the trigonometric function.

Operations on all quantities: these operations can be used on dimensionless and on dimensioned quantitities. The result of the function is a quantity object which automatically has the correct quantity type. In some cases this object is a generated transient unnamed object, however, in other cases, it is an unnamed variable quantity object. The handling of these two types of objects in user code should be different (see below). If not mentioned otherwise, the calculation is done on the value in the storage unit.

operation	example function call	comments
unary+	Time t(1.0); // construction, 1 s Time t1 = +t; // t1 contains 1 s +t = t1; // not allowed: temporary returned from +t is const	return an object with the value of the object itself (no change in sign) the return quantity type is identical to that of the original object; assignment to this object is not allowed.
unary-	Time t(1.0); // construction, 1 s Time t1 = -t; // t1 contains -1 s -t = t1; // not allowed: temporary returned from -t is const	return an object with the negative value of the argument (sign change); the return quantity type is identical to that of the original object; assignment to this object is not allowed.
prefix increment	Time t(1.0); // construction, 1 s Time t1 = ++t; // t contains 2 s, t1 contains 2 s Time t2 (5.0); // construction, 5 s ++t = t2; // t2 overwrites the incremented value: t contains 5 s	increment the value of the argument; the operator returns a reference to the changed original object; assignment to the return from this operator is possible; this operator is only defined for variable quantity objects, but not for constant or unique constant quantity objects.
postfix increment	Time t(1.0); // construction, 1 s Time t1 = t++; // t contains 2 s, t1 contains 1 s t++ = t1; // not allowed: temporary returned from t++ is const	increment the value of the argument; to mimic the behavior of the predefined postfix increment operator for built-in types, the operator returns to a const temporary copy of the unchanged original object; assignment to this object is not allowed; the operator is only defined for variable quantity objects, but not for constant or unique constant quantity objects.
prefix decrement	Time t(1.0); // construction, 1 s Time t1 = --t; // t contains 0 s, t1 contains 0 s Time t2 (5.0); // construction, 5 s --t = t2; // t2 overwrites the decrremented value: t contains 5 s	decrrement the value of the argument; the operator returns a reference to the changed original object; assignment to the return from this operator is possible; this operator is only defined for variable quantity objects, but not for constant or unique constant quantity objects.
postfix decrement	Time t(1.0); // construction, 1 s Time t1 = t--; // t contains 0 s, t1 contains 0 s t-- = t1; // not allowed: temporary returned from t-- is const	decrrement the value of the argument; to mimic the behavior of the predefined postfix decrrement operator for built-in types, the operator returns to a const temporary copy of the unchanged original object; assignment to this object is not allowed; the operator is only defined for variable quantity objects, but not for constant or unique constant quantity objects.
operator*	Time t(1.0); // construction, 1 s Time t1 = t * 5; // t1 contains 5 s	multiply from the right; The object to the right of the operator can not only be of the storage type. This is no problem, if the type of this object is such that it can safely be converted or promoted into the storage type of the quantity object. Thus, the above statement should give the desired result, since the `int` value can readily be converted into the default storage type `double`, and the result be used for the multiplication. However, if precision is lost during such a conversion, care should be taken. For example, IntTime t(1.0); // construction, 1 s (integer value) IntTime t1 = t * 1.3; // will loose fraction part of double value // 1.3 In some cases, the compilation process will issue a warning or even an error with such a construct. As with construction of quantity objects (see Construction of Quantity Objects), due to the promotion/conversion properties of C++, possibly non-meaningful constructs can be written, e.g. Time t(1.0); // construction, 1 s (integer value) Time t1 = t * 'a'; // will use encoding for character 'a', // depending on the character set. In any case, the return quantity type is identical to that of the original object, except for the fact that a variable object is returned even if a constant or unique constant object is multiplied.
operator*	Time t(1.0); // construction, 1 s Time t1 = 5 * t; // t1 contains 5 s	multiply from the left; Similar comments as regards the storage type as given above for the multiplication from the right apply here. The return quantity type is identical to that of the original object, except for the fact that a variable object is returned even if a constant or unique constant object is multiplied.
operator*=	Time t(1.0); // construction, 1 s t *= 5; // t contains 5 s	multiply by an object of storage type from the right and assign to the object itself; the object must be of variable mode; Similar comments as regards the storage type as given above for the multiplication from the right apply here. the return quantity type is identical to that of the original object; no new object is generated
operator/	Time t(1.0); // construction, 1 s Time t1 = t/5; // t1 contains 0.2 s	divide by an object of storage type on the right and assign to the object itself; the object must be of variable mode; Similar comments as regards the storage type as given above for multiplication apply here. the return quantity type is identical to that of the original object; no new object is generated
operator/	Time t(1.0); // construction, 1 s Time t1 = 5/t; // ERROR Frequency f = 5/t; // f contains 5 Hz	divide an object of storage type by quantity object; the return quantity type differs from that of the original object; the numerical result is calculated from the value in the standard unit
operator/=	Time t(1.0); // construction, 1 s t /= 5; // t contains 0.2 s	divide by an object of storage type and assign to the object itself; Similar comments as regards the storage type as given above for multiplication apply here. the return quantity type is identical to that of the original object; no new object is generated
sqrt	Area a(1.0); // construction, 1 m^2 Area a1 = sqrt (a); // ERROR Length l = sqrt(a); // l contains 1 m	calculate the square root; the return quantity type differs from that of the original object; the numerical result is calculated from the value in the standard unit; first alternative
sqrt	Area a(1.0); // construction, 1 m^2 Area a1 = a.sqrt(); // ERROR Length l = a.sqrt(); // l contains 1 m	calculate the square root; the return quantity type differs from that of the original object; the numerical result is calculated from the value in the standard unit; second alternative
abs	Time t(-1.0); // construction, -1 s Time t1 = abs(t); // t1 contains 1 s	calculate the absolute value; the return quantity type is a variable with identical dimension and unit as the argument; the old C style fabs() function is not provided, since abs() is overloaded for various data types in C++
ceil	Time t(1.1); // construction, 1.1 s Time t1 = ceil(t); // t1 contains 2 s	calculate the smallest integer value not less than the argument; the return quantity type is a variable with identical dimension and unit as the argument;
floor	Time t(1.1); // construction, 1.1 s Time t1 = floor(t); // t1 contains 1 s	calculate the largest integer value not greater than the argument; the return quantity type is a variable with identical dimension and unit as the argument;
modf	Time t(1.1); // construction, 1.1 s Time t_int; // default construction, // will be overwritten Time t1 = modf(t, &t_int); // t1 contains 0.1 s // t_int contains 1 s Time t2(30.1); // construction, 30.1 s MinuteTime tm_int; // default construction Time t1 = modf(t, &tm_int); // t1 contains 0.1 s // tm_int contains 0.5 min	decompose the first argument into integer and fraction parts; the return quantity type corresponds to that of the first argument; it is always of mode variable, irrespective of the mode of the first argument; this quantity object contains the fraction part; the second argument must be a pointer to an object of the same quantity type or a quantity derived from the same base quantity as that of the first argument; this quantity object returns the integer part
frexp	Time t(9.1); // construction, 9.1 s int int_power; // for storage of power result Time t1 = frexp(t, &int_power);// t1 contains 0.56875 s // int_power contains 4	decompose according to the C math.h frexp function; the return quantity type is a variable with identical dimension and unit as the first argument; this quantity object contains the normalized fraction part; the second argument must be a pointer to an object of type int; this quantity object contains the integer power of 2
ldexp	Time t(0.56875); // construction, 0.56875 s Time t1 = ldexp(t, 4); // t1 contains 9.1 s	compose according to the C math.h ldexp function; the return quantity type is a variable with identical dimension and unit as the first argument; this quantity object contains the composed quantity; the second argument must be an object of type int; this quantity object contains the integer power of 2
pow	Time t(2.); // construction, 2 s BSUtilities::Rational<long(2),long(1)> two; // declare a rational number: 2 SquareTime tsq = pow(t, two); // tsq contains 4 s^2 // Rational<N,D> is a rational number // with numerator N and denominator D // it is defined in namespace BSUtilities	raise the first argument to a power which is given as a rational number; the numerator and denominator of the Rational must be compile time constants; in general, the return quantity type differs from that of the original object, except for Rational<1,1> as the second argument; the result is calculated from the value in the standard unit. note: SquareTime is a quantity which holds squared times.
pow	Time t(2.); // construction, 2 s BSUtilities::Rational<long(2),long(1)> two; // declare a rational number: 2 SquareTime tsq = t.pow(two); // tsq contains 4 s^2 // Rational<N,D> is a rational number // with numerator N and denominator D // it is defined in namespace BSUtilities	raise the first argument to a power which is given as a rational number, alternative formulation; the numerator and denominator of the Rational must be compile time constants; in general, the return quantity type differs from that of the original object, except for Rational<1,1> as the argument the result is calculated from the value in the standard unit.
pow	Time t(2.); // construction, 2 s SquareTime tsq = pow(t, Loki::Int2Type<2>); // tsq contains 4 s^2	raise the first argument to an integral power; the integer must be a compile time constant and is converted into C++ type by Loki's Int2Type; in general, the return quantity type differs from that of the original object, except for Int2Type<1> as the second argument; the result is calculated from the value in the standard unit. note: SquareTime is a quantity which holds squared times.
pow	Time t(2.); // construction, 2 s SquareTime tsq = t.pow(Loki::Int2Type<2>); // tsq contains 4 s^2	raise the first argument to an integer power; alternative formulation; the integer must be a compile time constant and is converted into C++ type by Loki's Int2Type; in general, the return quantity type differs from that of the original object, except for Int2Type<1> as the argument the result is calculated from the value in the standard unit.
pow	Time t(2.); // construction, 2 s int i = 2; // run time int exponent SquareTime tsq = pow(t, i); // tsq contains 4 s^2, assignment SquareTime tsq1 (pow(t, i)); // tsq contains 4 s^2, copy construction double d = 2.0; // run time double exponent tsq = pow(t, d); // tsq contains 4 s^2, assignment tsq1 (pow(t, d)); // tsq contains 4 s^2, copy construction tsq = t.pow(d); // alternative formulation Time t1 (pow(t, i)); // results in DimensionMismatch exception	raise the first argument to a power which is given as an integer or as a double; this is a dynamic version of the pow function, and i or d can be variables at run time; float exponents are also possible; for all cases, also the alternative formulation is provided; in general, the return quantity type differs from that of the original object, except for i = 1 as the second argument; since the exact return type is not known at compile time, the result of pow is returned as a dynamic quantity object (type Dynamic<ST>, where ST is the storage type); this can be assigned to a commensurable variable object or such an object can be copy constructed; if the object assigned to or to be constructed is incommensurable, this is detected at run time and a DimensionMismatch exception (Exceptions) is thrown; the returned dynamic quantity object can not be used directly in further calculations, rather it should be converted immediately into a commensurable variable object; this improves safety when working with such values; the result is calculated from the value in the standard unit; however, any combination of allowed units is possible. Thus, Time t (300.); // construction, 300 s MinuteTime tm (5.); // construction, 5 min int exp = 2; // exponent SquareTime tsq (pow (t, exp)); // tsq = 90000 s^2 SquareTime tsq1 (pow (tm, exp)); // tsq1 = 90000 s^2 SquareMinuteTime tsqm (pow (t, exp)); // tsqm = 25 min^2 SquareMinuteTime tsqm1 (pow (tm, exp)); // tsqa1m = 25 min^2

Note, that the transient unnamed objects generated in some of the cases above do have only limited unit information. The value in such a return object is given in the standard unit. It is recommended that such objects are immediately copied into

 MinuteTime t (1.0, Minute());        // construction, 1 min
 Time t1 (sqrt (t) * sqrt (t));       // square of the square root 
                                      // should give 1 min
                                      // 60 s returned and copied into t1
 MinuteTime t2 (sqrt (t) * sqrt (t)); // return value 60 s is copied
                                      // into t2 - 1 min

or assigned to

 MinuteTime t (1.0, Minute());        // construction, 1 min
 Time t1 = sqrt (t) * sqrt (t));      // square of the square root 
                                      // should give 1 min
                                      // 60 s returned and assigned to t1
 MinuteTime t2 (sqrt (t) * sqrt (t)); // return value 60 s is assigned
                                      // to t2 - 1 min

a variable or constant quantity object of a commensurable type.
Note that in some cases such recalculations may provide surprising results. For example, assume that the recalculation factor between 1 s^2 and 1 min^2 is defined as 1200,

 MinuteTime t (4.1);       // construction, 4.1 min
 BSUtilities::Rational<long(2), long(1)> two;
                           // define a rational number 2
 SquareTime tsq = pow (t, two);
                           // square t, tsq contains: 60516 s^2
 SquareMinuteTime tsqm = pow (t, two);
                           // square t, tsqm contains: 50.43 min^2
 Time t_root = sqrt (tsq); // square root of tsq, t_root contains 246 s
 MinuteTime tm_root = sqrt (tsqm);
                           // square root of tsqm, 
                           // tm_root contains 4.1 min

The value of 4.1 min is first recalculated into 246 s, which is then squared to get 60516 s^2. Assignment to a SquareTime (which is in s^2) results in exactly this value, while assignment to SquareMinuteTime (in min^2) results in 50.43 min^2, which is not the expected numerical value of 4.1 x 4.1 = 16.81. However, taking the square root of both these results, we get the expected values.
Such problems occur with mathematical operators and functions which do their calculation in the standard unit, as mentioned above. In particular, this is the case for the sqrt and pow functions, as well as operator/ (divide an object of storage type by quantity object).
Finally note, that if one calls the mathematical functions with an argument of generated transient type, this argument's value is standardized. Consequently, the return value will always be calculated on the basis of this standardized value. This may also provide unexpected results. For example, the frexp function, which by classical definition returns a result between 0.5 and 1.0, might result in values of the quantity object asigned to being out of this interval.

 MinuteTime tm (4.251);     // construction, 4.251 min
 int i;                     // to receive the integer exponent
 Time t = frexp (tm, &i);   // apply frexp function, result
                            // t = 31.885 s, i = 3
 Time t1 (3.2);             // construction, 3.2 s
 MinuteTime tm1 = frexp (t1, &i)
                            // apply frexp function, result
                            // tm1 = 0.01333 min, i = 2

Of course, the classical definition is followed if assignment is to a variable with the same unit as the first argument of the frexp function:

 MinuteTime tm (4.251);     // construction, 4.251 min
 int i;                     // to receive the integer exponent
 MinuteTime tm1 = frexp (tm, &i)
                            // apply frexp function, result
                            // tm1 = 0.531375 min, i = 3

Mathematical Operations Linking Two Quantity Objects

Among the mathematical operations linking two quantity objects, some require that the two objects are commensurable, i.e. for addition.

commensurability check necessary

the += (add and assign) operator. This operator is used to add a quantity object to a variable and assign the result to the latter. The left hand side argument of this operator must be a variable, while the right hand side operator can be of any quantity mode.

              Time t (60.);            // construction, 60 s
              Time t1 (10.);           // construction, 10 s
              t += t1;                 // result: t is now 70 s
              TimeConstant tc (20.);   // construction, 20 s
              t += tc;                 // result: t is now 90 s

Chaining of this operator is possible:

              Time t (60.);            // construction, 60 s
              Time t1 (10.);           // construction, 10 s
              Time t2 (20.);           // construction, 20 s
              t += t1 += t2;           // result: t is now 90 s
                                       //         t1 is now 30 s

It is, however, required that both arguments are commensurable. This is the case if they are derived from the same base quantity,

              Time t (60.);            // construction, 60 s
              MinuteTime tm (1.);      // construction, 1 min
              t += tm;                 // result: t is now 120 s

in which case the result is recalculated into the unit of the left hand side argument, or if the right hand side argument is a generated quantity and the two dimensions are identical:

              Time t (2.);             // construction, 2 s
              SquareTime tsq  = t * t; // construction, 4 s^2
              t += tsq/t;              // result: t is now 4 s
              t += tsq * t             // ERROR

If the two argument quantities are incommensurable, the compiler will catch this error. Note, that incommensurability is assumed if the second quantity object is not generated and has a base quantity different from that of the first one.

The generated quantity may be only at the right hand side of a += operator, but not on the left hand side, since generated quantities are not design to be assigned to.

the -= (subtract and assign) operator. All comments above for the += operator also apply to operator -=. For example,

              Time t (60.);            // construction, 60 s
              Time t1 (10.);           // construction, 10 s
              t -= t1;                 // result: t is now 50 s
              TimeConstant tc (20.);   // construction, 20 s
              t -= tc;                 // result: t is now 30 s
              Time t2 (20.);           // construction, 20 s
              t -= t1 -= t2;           // result: t is now 70 s
                                       //         t1 is now -10 s
              MinuteTime tm (1.);      // construction, 1 min
              t -= tm;                 // result: t is now 0 s

the binary + (add) operator. All combinations discussed for the += operator can also be used with operator+, and the same restrictions apply.
the binary - (subtract) operator. All combinations discussed for the -= operator can also be used with operator-, and the same restrictions apply.

the atan2 function. The two arguments of this function must be commensurable. The values of both quantity objects are recalculated into the standard unit, and the final result is calculated from the resulting numerical values and returned as an object of a dimensionless generated variable.

              Time t (5.);                          // construction, 5 s
              MinuteTime tmin (0.5);                // construction, 30 s 
              PureNumber result = atan2 (t, tmin);  // calculate result:
                                                    // 0.165149, assigned
                                                    // to PureNumber object

Note that this usage of the atan2 function differs from the other form (atan) in a way that in the present case, dimensioned quantity objects can be used, while this is not possible for the atan form.

the fmod function. In most cases, the two arguments of this function should be derived from the same base quantity. They can be of mode variable, constant and unique constant. In contrast to the case of the atan2 function above, the final result is again a quantity object and not of storage type. The type of the base object corresponds to the type of the first argument of the fmod function. However, if these are of mode constant or unique constant, a corresponding quantity object of mode variable is returned. The value of the return quantity object is always recalculated into the storage unit of the first argument of this function.
```
              Time t (7.);                // construction, 7 s
              Time t1 (2.);               // construction, 2 s
              Time t2 = fmod (t, t1);     // result: 1 s
```
Either the first or the second argument, or both, can also be a generated transient quantity object. In this case, however, the dimensions of the two arguments must be commensurable.

commensurability check not necessary
- the * (multiply) operator. Two quantity objects can be multiplied unconditionally. The return object of operator* is a generated transient unnamed quantity object. It should immediately be assigned to a variable of commensurable type:
```
          Length m (10.0);            // construction, 10 m
          Area A = m * m;             // A = 100 m^2
```
- the / (divide) operator. Two quantity objects can be divided unconditionally. The return object of operator/ is a generated transient unnamed quantity object. It should immediately be assigned to a variable of commensurable type:
```
          Time t (5.0);               // construction, 5 s
          Length m (10.0);            // construction, 10 m
          Velocity v = m/t;           // v = 2 m s^-1
```
  This is even the case if the two objects are of types derived from the same base quantity (PureNumber is a quantity object which is dimensionless):
```
          Time t (5.0);               // construction, 5 s
          MinuteTime tm (1.0);        // construction, 1 min
          PureNumber r = t/tm;        // r = 12
```
The operators *= (multiply and assign) and /= (divide and assign) for the case of two quantity arguments are not provided. They would only make sense if at least one of the arguments were dimensionless. In all other cases this would lead to an incommensurability problem in the assignment.

Comparison Operations with Quantity Objects

Client programs can compare quantity objects using the conventional comparison operators == (equal), != (not qual), < (less than), > (greater than), >= (less equal), and <= (greater equal). All these operations are defined such that the values of the two objects are compared after recalculation to a common unit. Thus, comparisons are not only allowed between quantity objects of the same quantity type, but also between any object related by the same base quantity. In particular, the storage unit or the storage type may be different.

Time t (60.);                 // construction, 60 s
MinuteTime t1 (1.);           // construction, 1 min
if (t == t1)                  // result: true
  // ...
IntTime tint (7);             // construction, 7 s
if (t != tint)
  // ...                      // result: true

Quantity objects which are not related by a base quantity in general can not be compared. Consequently, the following is invalid:

Time t (60.);                 // construction, 60 s
Length l (1.);                // construction, 1 m
if (t == l)                   // ERROR
  // ...

Only if the conversion of the right hand side object in the comparison operation into an object of the left hand side type is allowed, the comparison statement is legal. Thus, the following is valid:

ThermodynamicTemperature T (273.15);        // construction, 273.15 K
CelsiusTemperature Tc (0.)                  // construction, 0 oC
if (T == Tc)                                // result: true
  // ...

Comparison to unnamed transient quantity objects is allowed as long as the two quantities are commensurable:

Time t (1.);                  // construction, 1 s
Time t1 (2.);                 // construction, 2 s
if (t == (t * t1)/t)          // comparison: false
  // ...

Furthermore, dynamic quantity objects may be compared to quantity objects:

Time t (1.);                 // construction, 1s
SquareTime tsq = t * t;      // value: 1 s^2
double power = 0.5;          // define the power (i.e., take square 
                             // root)
if (t == pow (tsq, power))   // comparison: true
  // ..

if (pow (tsq, power) == t)   // also possible
  // ..

if (pow (tsq, power) == pow (tsq, power))   // also possible
  // ..

Here, the power function returns an object of type Dynamic<ST>, which is compared to the Time object. Such a comparison only makes sense if the two objects are commensurable, i.e. have the same dimension. With dynamic quantity objects, this can only be tested at run time, which decreases performance and may compromise type safety. Thus, such constructs should be used only when dynamic access is absolutely necessary.

For comparison operations, the mode of any of the two quantity objects is not important. Thus, for example, it is allowd to compare a variable quantity onject to a constant quantity object, provided the above conditions are met:

Time t (1.0);                // construction, 1 s
TimeConstant tc (5.0);       // construction, 5 s
if (t == tc)                 // comparison: false
  // ..
LengthConstant lc (1.);      // construction, 1 m
if (t <= lc)                 // ERROR
  // ..

The comparison operations provided by the Quantities package simply compare the numerical values of the two quantity objects concerned. They do not take into account problems caused by the particular storage type of the value. For example, it is well known that comparison operations of floating point values (in particular the equality operation) can be dangerous and special precautions should be taken to avoid problems. For details, see the following links

The Quantities package does not implement any of the schemes described in these references. Thus, if necessary, this has to be included in client code.

Logical Operations with Quantity Objects

In the present version, no logical operations (AND, OR, not, bitwise operations) are provided for quantity objects.

Input and Output Operations with Quantity Objects

Input and output of quantity objects into and from streams and strings is implemented. For such operations you should use operator>> and operator<<. One quantity object can be located on any side of these operators. Furthermore, a std::string can directly be assigned to a variable quantity object. The behavior of these input/output functions can be controlled by additional helper objects.

Serialization [BoostSerialization] can be also regarded as a particular type of input/output. This will be discussed in a separate section.

Unit Symbol Interpretation

The grammer which defines a well-formed unit symbol is discussed Unit Symbol Grammar elsewhere. Well-formed-ness of a symbol is only a formal requirement, it is not necessarily a symbol that is accepted for a particular quantity.

Well-formed symbols of non-prefixable and prefixed units consist of strings of alphabetical characters. In the case of composed units, the components are separated by a blank character and each component may be appended by an exponent starting with the character `^'. The exponent may be given as the quotient of two long integers, with the numerator being positive or negative, while the denominator must be positive. Zero is not allowed as one of the numbers. Numerator and enominator are separated by the character `/'. The denominator can be omitted, which is interpreted as it being 1. In addition, the numerator can be omitted, which is interpreted as the total exponent being 1.

Here are some examples of correct unit symbols:

min - the symbol of minute, a non-prefixable unit
m - the symbol of the metre, a prefixed unit with the empty prefix
mm - the symbol of the millimetre, a prefixed unit with the milli prefix
mm s^-1 - the symbol for a unit composed of mm and s with corresponding exponents (1/1 and -1/1)
cm^2 s^-1 - the symbol for a unit composed of cm and s with corresponding exponents (2/1 and -1/1)
kg (m^2)^-1 - the symbol of a composed unit with a composed component

The following examples are not well-formed:

(mm - unbalanced parenthesis
mm) - unbalanced parenthesis
mm^1/-2 - denominator not a positive integer
mm^1.0 - numerator not an integer

To be acceptable as a particular quantity's unit symbol, the string must additionally be a valid unit symbol. Thus,

it must correspond to one of the units that are defined in the quantity's unit list
if it is a prefixed unit, it's first characters must correspond to the symbol string of one of the unit prefixes, and the following characters must match the base symbol string of the underlying prefixable unit. As a special case the prefix may be omitted. This corresponds to the NoPrefix.
if it is a composed unit, the number of components and the exponents must match the respective properties of the underlying compose base unit. A numerator or denominator of 0 will be accepted as well-formed, but will probably be invalid, since both cases would result in useless exponents: If the numerator is 0, the total exponent is also equal to 0, which will not make a useful unit component; if the denominator is 0, the total exponent is equal to infinity.

In some cases, there might be alternative formulations for composed units of a particular quantity. For example, the composed unit for a specific area, m^2 kg^-1 (a length unit squared divided by a mass unit), can alternatively be formulated as (m^2) kg^-1 (an area unit divided by a mass unit). These alternatives are fully equivalent for use and differ only in the representation and substitution possibilities in the graphical user interface.

Output Operations with Quantity Objects

Quantity objects of all modes can be used in output statements. Any ostream object can be used for output of a quantity. Thus, output is not only possible into one of the global ostream objects (cout, cerr, clog), but also into objects of types std::ostringstream (i.e., into a string) or std::ofstream (i.e., into a file). For usage details of these objects see any current reference to the C++ standard library, for example [Josuttis_1999]. For many of these output operations use operator << with the stream object to the left of this operator, or operator >> with the stream object to the right of this operator:

  #include <iostream>
  Time t (1.0);               // construction, 1 s
  cout << t;                  // write "1 s" to cout
  t >> cout;                  // write "1 s" to cout

If ostringstreams (and output file streams) are to be used for output, the corresponding objects have to be constructed first:

  #include <sstream>              // include header
  #include <fstream>              // include header

  std::ostringstream oss;         // construct output string stream
  Time t (5.0);                   // construction, 5 s
  oss << "a time quantity: " << t;// write text and "5 s" to stream
  std::string s (oss.str ());     // extract string from stream
                                  // and store it into s

  std::ofilestream ofs ("f.txt"); // construct output file stream
                                  // to file named f.txt
  Time t (5.0);                   // construction, 5 s
  ofs << "a time quantity: " << t;// write text and "5 s" to stream

This example also demonstrates that output of a quantity object can be intermixed with output of objects of other types.

Since unnamed transient objects do not carry information about the unit, their direct output is incomplete and contains the string "(unknown unit)". Thus, assignment to a commensurable object prior to output is strongly recommended:

  Time t (5.0);                   // construction, 5 s
  cout << (t * t)/t;              // writes "5 (unknown unit)"
  Time t1 = (t * t)/t;            // writes "5 s"
  cout << (t1 = (t * t)/t);       // alternative, writes "5 s"

Note in the latter, alternative formulation that the assignment has to be included into parentheses.

Output of quantity objects into a string can be done also directly, without using a stringstream:

  Time t (2.0);                   // construction, 2 s
  std::string s1;                 // construct string
  t >> s1;                        // s1 contains "2 s"
  std::string s2;                 // construct string
  s2 << t;                        // s2 contains "2 s"

Furthermore, a conversion of a quantity object into a std::string is provided:

  Time t (2.0);                   // construction, 2 s
  std::string s1 (t);             // construct string,
                                  // store "2 s"

Input Operations with Quantity Objects

Input operations from input streams and from strings can only be performed into variable quantity objects. Any input stream (e.g., the global cin stream, or any std::istringstram od std::ifstream) or string can be used as the source of information. For usage details of these objects see any current reference to the C++ standard library, for example Josuttis [Josuttis_1999]. Operator>> and operator<< are used to direct information into a variable quantity object placed to the right or left of the operator, respectively. The input stream or the string must be placed on the respective other side of the operator. Interpretation of the input data is based on the control objects placed in the input stream (see, Control Objects for Input and Output). Per default, it is assumed that the input stream or string contains a value and a unit symbol. The following examples use an input string stream or a string.

  Time t;                           // default construction, 1 s
  std::istringstream is ("5.0 s");  // define an input string stream
  iss >> t;                         // input from left: t = 5 s
  std::istringstream is1 ("6.0 s"); // define an input string stream
  t << iss1;                        // input from right: t = 6 s
  "7.0 s" >> t;                     // input from left: t = 7 s
  t << "8 s";                       // input from right: t = 8 s

The substring representing the value of the variable is converted into the storage type. If this conversion fails, an InputError exception (Exceptions) is thrown:

  Time t;                           // default construction, 1 s
  t << "xxxx s";                    // InputError thrown

If the unit symbol does not correspond to one of the quantity's unit's symbols, also an InputError (Exceptions) is thrown:

  Time t;                           // default construction, 1 s
  t << "3.5 x";                     // InputError thrown

If the unit is omitted in the input information, the storage unit of the variable object is assumed:

  Time t;                           // default construction, 1 s
  t << "60";                        // read without unit: t = 60 s
  MinuteTime tm;                    // default construction, 1 min
  tm << "60";                       // read without unit: tm = 60 min

For input from a string, there is an alternative formulation, which allows an assignment-type syntax:

  Time t;                           // construction, 1 s
  t = "720 s";                      // assign, t = 720 s
  MinuteTime tm;                    // construct, 1 min
  tm = "10 min";                    // assign, tm = 10 min
  tm = "30 s";                      // re-assign, tm = 0.5 min

Note, that if input of name and/or symbol of the quantity is requested by the respective control objects (Control Objects for Input and Output), these items must be present in the input. If they are absent in these cases, an InputError exception (Exceptions) is thrown.

Control Objects for Input and Output

Control objects manipulate the behavior of the input and output functions for quantity objects. In particular, they allow to switch on and off input and output of specific pieces of information (the name and the symbol of the quantity) and (for input) to define the unit which is assumed for the interpretation of the input value. Without using the control objects, neither the name nor the symbol of the quantity object are given to the output stream or read from the input stream. Also, per default, without defining a unit for input by a control object, it is assumed that the value is given in the storage unit of the quantity object, if a unit symbol is not present in the input. If name or symbol input is requested, per default it is mandatory to place an equal sign between these strings and the quantity object's value. This behaviour can be switched off. After having switched on input or output or having defined an input unit, this state will remain in effect until it is switched off, or until another input unit is defined. If either name of symbol output is switched on, an equal sign is also placed in the output between the name and/or symbol and the value of the quantity object.

The control objects excert their function by being placed in a stream as shown by the examples below. If several output or input streams are used, they affect all streams for which they are defined. Thus, if a control object is placed in the global cout stream, it will also affect output into an output file stream. Output control objects do also have an effect on conversion of a quantity object into a std::string (see Output Operations with Quantity Objects). Similarly, if placed in cin, a control object also affects input through an input string stream or other input possibilities.

Instances of the following control objects can be placed in an output stream.

PrintName<true> () -- switch on output of quantity name. Subsequent output of a quantity will include the quantity object's name.

Time t (1.0);                // construction, 1 s
t.name ("time");             // set name to "time"
cout << t << endl;           // prints "1 s"
cout << PrintName<true> ()
     << t << endl;           // prints "time = 1 s"

PrintName<false> () -- switch off output of quantity name. Subsequent output of a quantity will not include the quantity object's name (default).

PrintSymbol<true> () -- switch on output of quantity symbol. Subsequent output of a quantity will include the quantity object's symbol.

Time t (1.0);                // construction, 1 s
t.symbol ("t1");             // set symbol to "t1"
cout << t << endl;           // prints "1 s"
cout << PrintSymbol<true> ()
     << t << endl;           // prints "t1 = 1 s"

PrintSymbol<false> () -- switch off output of quantity symbol. Subsequent output of a quantity will not include the quantity object's symbol (default).

Note, that placing such objects in an std::istream will cause a compile time error.

Instances of the following control objects can be placed in a std::istream:

ReadName<true> () -- switch on input of quantity name. If this control object has been used, all subsequent inputs must include a quantity name and an equal sign (default), until input of a name is explicitly switched off. Not providing a name and an equal sign will result in an InputError. Requesting the equal sign can be switched off with ReadEqual<false> (see below).

Time t;                   // default construction, 1 s
t = "2.5 s";              // input without name, t = 2.5 s
cin >> ReadName<true> (); // switch input of quantity name on
t = "timename = 2.5 s";   // sets also the name
t = "2.5 s";              // throws InputError  
t = "timename 2.5 s";     // throws InputError

ReadName<false> () -- switch off input of quantity name. Subsequent input of a quantity will not expect the quantity object's name (default).

ReadSymbol<true> () -- switch on input of quantity symbol. If this control object has been used, all subsequent inputs must include a quantity symbol and an equal sign (default), until input of a symbol is explicitly switched off. Not providing a symbol and an equal sign will result in an error. Requesting the equal sign can be switched off with ReadEqual<false> (see below).

Time t;                     // default construction, 1 s
t = "2.5 s";                // input without name, t = 2.5 s
cin >> ReadSymbol<true> (); // switch input of quantity symbol on
t = "timesymbol = 2.5 s";   // sets also the symbol
t = "2.5 s";                // throws InputError  
t = "timesymbol 2.5 s";     // throws InputError

ReadSymbol<false> () -- switch off input of quantity symbol. Subsequent input of a quantity will not expect the quantity object's symbol (default).

ReadEqual<true> () -- switch on input of quantity equal sign. Subsequent input of a quantity will expect an equal sign between the quantity object's name and symbol and the value, if name or symbol reading is switched on (default).

Time t;                     // default construction, 1 s
t = "2.5 s";                // input without name, t = 2.5 s
cin >> ReadSymbol<true> (); // switch input of quantity symbol on
t = "timesymbol = 2.5 s";   // sets also the symbol
t = "2.5 s";                // throws InputError  
t = "timesymbol 2.5 s";     // throws InputError  
cin >> ReadEqual<false> (); // swith off request for "="
t = "timesymbol 2.5 s";     // now this is ok

ReadEqual<false> () -- switch off input of quantity equal sign. Subsequent input of a quantity will not expect an equal sign between the quantity object's name and symbol.

ReadUnit<U> () -- set unit U to be assumed for input of a quantity.

Time t;                     // default construction, 1 s
t = "2.5";                  // input without unit, t = 2.5 s
cin >> ReadUnit<Minute> (); // switch interpretation to Minute 
t = "2.5";                  // now t = 150 s

Throws an InputError if the symbol of U is not found in the list of symbols allowed for the quantity object.

Time t;                     // default construction, 1 s
t = "2.5";                  // input without unit, t = 2.5 s
cin >> ReadUnit<Metre> ();  // switch interpretation to Metre 
t = "2.5";                  // throws InputError, Metre not allowed
                            // for Time

ReadUnit<NoUnit> () -- switch off any assumption of unit for input of a quantity.

Time t;                     // default construction, 1 s
cin >> ReadUnit<Minute> (); // switch interpretation to Minute 
t = "2.5";                  // input without unit, t = 150 s
cin >> ReadUnit<NuUnit>;    // switch off interpretation as min
t = "2.5";                  // now t = 2.5 s

Note, that placing such objects in an std::ostream will cause a compile time error.

Note also, that the implementation does not distinguish between a string in the input being a name or a symbol for a quantity object. All tokens in the input will be read subsequently and interpreted in the order name, symbol, equal sign, value, and unit symbol.

Conversion Operations between Quantity Objects

Conversion between quantity objects is usually only possible if the source and target object are related to the same base quantity. One notable exception are objects of the various temperatures.
Some conversions have already been mentioned in paragraph Construction of Quantity Objects. In these cases the conversion is performed during the construction of a new quantity object. However, sometimes it is desired to convert and return the value of an existing quantity object without the overhead of creating a new quantity object.

You can generate a new (possibly transient) quantity object with the recalculated value:.

  Time t(60.0):                       // construction, 60 s
  MinuteTime tm = t (Minute ());      // return value in min, 
                                      // new transient object returned,
                                      // tm = 1.0 min
  MinuteTime tm1 (t (Minute ()));     // return value in min, 
                                      // new transient object returned,
                                      // tm1 = 1.0 min; alternative

The two alternatives should give the same result.
Another possibility is to recalculate the quantity objects value to another unit and return the resulting value:

  Time t(60.0);                       // construction, 60 s
  double t_min = t.value (Minute ()); // return value in min, 
                                      // no new object generated,
                                      // t_min = 1.0

Similarly, the conversion can be triggered by a string which corresponds to a symbol string of a unit, which is associated with the base quantity of the quantity to be converted:

  Time t(60.0);                       // construction, 60 s
  double t_min = t.value ("min");     // return value in min, 
                                      // no new object generated,
                                      // t_min = 1.0

Serialization ofQuantity Objects

... describe the use of serialization ... ... serialization of UniqueConstant is not allowed nor necessary ...

Status Report Operations with Quantity Objects

Some operations are provided in order to allow the extraction of certain pieces of information from a quantity object. It is noted that by necessity such information is incomplete as compared to the information stored in the quantity object. For example, if a value is extracted, it is just a number in the storage type without carrying information about the unit in which it is given or the dimension.

value reporting operations; These operations return the value of the quantity object in the storage type without any additional information. Reporting of this number in a unit different from the storage unit as implemented in versions up to 1.2.1 is no longer possible.

value () returns the value in the storage unit

  Time t(1.0);                            // construction, 1 s
  double t1 = t.value ();                 // t1 = 1.0
  MinuteTime tmin(1.0);                   // construction, 1 min
  double tmin1 = tmin.value ();                 // t1 = 1.0

standard_value () returns the value in the storage unit

  Time t(1.0);                            // construction, 1 s
  double t1 = t.standard_value ();        // t1 = 1.0
  MinuteTime tmin(1.0);                   // construction, 1 min
  double tmin1 = tmin.standard_value ();  // t1 = 60.0

Thus, in the second example, the contents of the MinuteTime object is 1 min, but the return value is 60 (after recalculation into the standard unit s).

name/symbol reporting operations

quantities can be interrogated for their name and symbol:

Time t;                              // default construction
t.name ();                           // returns the name
t.symbol();                          // returns the symbol

unit reporting operations There are two sets of operations which report properties of the storage unit within a quantity object or class.

The functions in the first set, unitsymbol () and unitname (), allow dynamic access to the requested information. They can be called on a particular object, i.e. an instance of a quantity class.
- unitsymbol () returns the string of the unit symbol
```
  Time t(1.0);                            // construction, 1 s
  std::string symbol = t.unitstring ();   // string contains "s"
```
- unitname () returns the name of the unit symbol
```
  MinuteTime t(1.0);                  // construction, 1 s
  std::string name = t.unitname ();   // string contains "minute"
```
  The functions in the second set, Unitsymbol () and Unitname (), allow static access to the requested information. They can be called on a class name, which is known at compile time, without having to create an instance of that class.
  - Unitsymbol () returns the string of the unit symbol
```
  std::string symbol = Time::Unitstring ();   // string contains "s"
```
  - Unitname () returns the string of the unit symbol
```
  std::string name = Time::Unitname ();   // string contains "second"
```
- operations reporting properties of the quantity
  - symbol () symbol () reports the symbol of the quantity object.
```
  Time t(3.0);                            // construction, 3 s
  t.symbol ("t_1");                       // set the symbol of t
  std::string symbol = t.symbol ();       // symbol contains "t_1"
```
    Per default, after construction, the symbol string of the object is pre-determined. However, the symbol may be set later in Variables and Constants (see Status Change Operations with Quantity Objects).
  - name () reports the name of the quantity object.
```
  Time t(3.0);                            // construction, 3 s
  t.name ("time");                        // set the name of t
  std::string name = t.name ();           // name contains "time"
```
    Per default, after construction, the name string of the object is pre-determined. However, the name may be set later in Variables and Constants (see Status Change Operations with Quantity Objects).
  - IsDimensionless provides static access to query a class whether it is dimensionless. It can be called on a class name, which is known at compile time, without having to create an instance of that class.
```
  bool dim = Time::IsDimensionless ();       // dim is true
```
  - isDimensionless () provides dynamic access to query a class whether it is dimensionless. It is called on an instance of the class.
```
  Time t(1.0);                           // construction, 1 s
  bool dim = t.isDimensionless ();       // dim is true
```
  The dynamic routines listed in this section are virtual. Thus, it is possible to generically work with pointers to a Quantities object, and still retrieve the desired information.
```
    Time t(1.0);                          // construction, 1 s
    ::Quantities::Quantities *q = &t;     // store generic pointer to t
    bool dim = q->isDimensionless ();     // dim is true
```

Status Change Operations with Quantity Objects

In most cases, the status of a quantity object should only be changed through the operations described above (e.g., assignment, mathematical operations). However, there are two exceptions from this rule, which refer to the setting of the name and the symbol of the quantity. These strings can be given by the default values for all modes, or set during construction for Variable and Constant objects. Furthermore, they may be set on an already existing quantity object for Variable or Constant by the following two functions:

name sets the name string in a quantity object. It uses an argument of type std::string.

      Time t;                           // default construction, 1 s
      std::string namestring ("time");  // define a string
      t.name (namestring);              // now t has name "time"

The implicit conversion of a character string into a std::string can be used to circumvent the explicit definition of a name string:

      Time t;                           // default construction, 1 s
      t.name ("time");                  // now t has name "time"

symbol sets the symbol string in a quantity object. It uses an argument of type std::string.

      Time t;                           // default construction, 1 s
      std::string symbolstring ("t");   // define a string
      t.symbol (symbolstring);          // now t has symbol "t"

The implicit conversion of a character string into a std::string can be used to circumvent the explicit definition of a symbol string:

      Time t;                           // default construction, 1 s
      t.symbol ("t");                   // now t has symbol "t"

Note that these functions are not available for a UniqueConstant quantity object.

Special Values of a Quantity Object

Four special values for each quantity type can be retrieved by the respective functions:

Time t1 = SpecialValues<Time>::unity ();    // t1 has value 1.0 s
Time t2 = SpecialValues<Time>::zero ();     // t2 has value 1.0 s
Time t3 = SpecialValues<Time>::NaN ();      // t3 has value not-a-number
Time t4 = SpecialValues<Time>::infinity (); // t4 has value infinity

The quantity type can not be a UniqueConstant.

Miscellaneous Functions and Operations on Quantity Objects

Some functions and operations which do not fit into any of the above sections are described in the following.

The version () function returns a std::string with some dynamic information about the version of the currently used implementation. For example, this information can be placed in an output stream:

  Time t(1.0);                        // default construction, 1 s
  cout << t.version () << endl;       // prints a line with version
                                      // information

... Version ... -> static info

Destruction of Quantity Objects

Quantity objects generated on the stack with operator new should later be explicitly deleted:

 Time *t = new (Time); 
 // ... use pointer to Time object t
 delete t;

The Graphical User Interface to Quantities

The graphical user interface (GUI) to quantities is an optional feature that requires the compilation of some specific libraries. Only if this has been requested at compile time, the feature is available. Moreover, the GUI requires the Qt4 system to be available. (to be updated)

Quantity Aggregates

VariableVector and VariableVectorIterator

A variable vector can be used to store several quantity values which are expressed in the same unit. Many physical quantities define a respective vector. A variable vector behaves mostly like a std::vector, for example

TimeVector tVec;         // create an empty time variable vector, unit: second
size_t s = tVec.size (); // size s is zero

This uses the default constructor. The vector can be initialized with default values, a certain number of elements, or elements from a certain range (given by iterators) of another vector (see the reference manual).

However, storing and retrieving values from the vector requires quantity objects::

TimeVector tVec;     // create an empty time variable vector, unit: second
Time t (5.);            // value: 5 s
tVec.push_back (t);     // store the value

Conversion of quantities is perfomed during storage:

MinuteTime tMin (1.0);  // value: 1 min = 60 s
tVec.push_back (tMin);  // second element in vector has value 60 s

Non-quantity values or non-convertible quantities can not be used to store elements of a variable vector:

tVec.push_back (20.);   // ERROR
Length l (10.);
tVec.push_back (l);     // ERROR, however:
CelsiusTemperatureVector tempVec;    // empty vector
ThermodynamicTemperature T (298.15);
tempVec.push_back (T);               // first element of vector is 0 degree
                                     // celsius

Data can be retrieved from the variable vector either with array style access or by iterator access:

std::cout << tVec[0];      // array style, prints 5 s
std::cout << *tVec.begin() // tVec.begin() is an iterator pointing to
                           // the first element, prints 5 s

To convert values into another unit, the return from the value has to be assigned to a quantity or used in a copy construction:

MinuteTime tMin1;
tMin1 = *(tVec.begin()+1);            // stores 1 min in tMin1
MinuteTime tMin2 (*(tVec.begin()+1)); // tMin2 is also 1 min

The last two example code lines also show the use of an iterator pointing into a variable vector. Normal, constant, reverse and constant reverse iterators are provided. They behave mostly like the respective iterators to a std::vector. However, dereferencing a variable vector iterator does not result in a reference to an alement of the vector, but rather to an additional variable object. Thus, any operation on the object returned when dereferencing a variable vector iterator hould be avoided:

TimeVector::iterator it = tVec.begin();  // points to first element 
std::cout << *it;                        // prints 5 s
Time avoid (10.);                        // avoid holds 10 s
*it = avoid;                             // does not affect the variable vector
                                         // and should be avoided

Variable vectors can be compared. Comparison takes into account possible conversions. Thus, an element `1 min' is equal to an element `60 s'. Variable vectors are compared element by element, they differ if they differ by length or (if they have equal length) by differences in elements.

Error Messages by the Compiler

The code of Quantities makes frequently use of metaprogramming techniques. Thus, the C++ compiler is internally used to perform calculations during compile time. For example, the compiler is instructed to check commensurability properties or the correctness of units. In this way, errors at run time can be minimized.

DimensionError<true> should occur in the compilers output, if incommensurability of dimensions is detected.
AssingmentError<true> should occur in the compilers output, if assignment to a generated quantity is detected.
UnitError<true> should occur in the compilers output, if an inappropriate unit has been used.

Note, that depending on the compiler used, these messages may be buried in a large number of output lines, and are often not easily found.

Exceptions

Quantities code may throw exceptions when it encounters during run time some unexpected situations. In addition, some exception-like error messages are generated during compilation (see Error Messages by the Compiler). Run time exceptions in Quantities are relatively rare since most errors are detected during compilation. However, dynamic problems may only be detected when the program runs and all information is available.

The following exceptions could be thrown:

InputError is thrown by input functions, if the input does not conform to the requirements, e.g. the input string is too short or does not contain requested substrings.
UnitMismatch is thrown if an operation (often a conversion) involving a unit is requested and the unit is not in the list of units available for the quantity objects type, or its base quantity's type.
DimensionMismatch is thrown if an operation involving a Dynamic quantity is requested and the dimensional information is incommensurable.
VectorOutOfBounds (to be written)

Technically, all these exceptions (except UnitMismatch) are derived from QuantityException. It is thus possible to check for that exception type:

  Dynamic q;
  int exp;
  exp = 1;                    // no exception expected
  try {q = pow (q, exp);}     // raising to power of 1 is ok
  catch (QuantityError)
  {
// handle exception
  }
  exp = 2;                    // exception expected
  try {q = pow (q, exp);}     // dimensions are incommensurable
  catch (QuantityError)
  {
// handle exception
  }

Alternatively, the more specific exceptions can be caught:

  Dynamic q;
  int exp = 2;                // DimensionMismatch expected
  try {q = pow (q, exp);}     // dimensions are incommensurable
  catch (DimensionMismatch)
  {
// handle exception
  }

QuantityError allows to transport a textual message. This message may be set when the exception is thrown. If the code does not set the message itself, a default text is provided. The message can be used when handling the caught exception:

  try {
 // ...                       // try some code
      }
  catch (DimensionMismatch error)
  {
    std::cout << error.message () << std:: endl;
                              // print out the text message
  }

Physical Quantities

(to be finalized)

The PhysicalQuantities library provides implementations of various quantities important in scientific work, on the basis of the Quantity library. These physical quantities are selected from the SI, and the library defines the most important units, including the SI unit, and if applicable other units in common use. For details, see the PhysicalQuantities page.

General Quantities

The GeneralQuantities library provides implementations of various generally useful quantities based on the Quantity library. For details, see the GeneralQuantities page.

References

[Sutter_2005] H. Sutter and A. Alexandrescu, C++ Coding Standards, Addison-Wesley, Boston, 2005, p. 4.

[Dewhurst_2003] S.C. Dewhurst, C++ Gotchas, Addison-Wesley, Boston, 2003, p. 129, p. 153 ff.

[BoostSerialization] http://www.boost.org/doc/libs/1_35_0/libs/serialization/doc/index.html

[Josuttis_1999] N.M. Josuttis, The C++ Standard Library. A Tutorial and Reference, Addison, Wesley Longman, Reading, 1999.

back to Quantities start page