Quan Index

fixed_quantity

Introducing Quan fixed_quantity

The fixed_quantity is a C++ representation of a physical_quantity where the unit is fixed at compile-time.It has many similar features to a built-in type ...

... but with added functionality ...

Motivation

Code clarity

Inbuilt-types representing physical quantities are in common use:

   struct Box {
      double length;
      double height;
      double width;
      Contents contents;

      double weight()
      {
         double volume = length * width * height;
         double mass = contents.material.density * volume;
         return mass * gravity;
      }
   };

In struct Box above almost every entity represents a physical quantity. One might assume the quantities are expressed in standard SI units, but to be sure requires consulting external documentation. A fixed_quantity (expressed in terms of the simple interface described later) is self-documenting:

   struct quan_box {
      quan::length::m length;
      quan::length::m width;
      quan::length::m height;
      quan::density::kg_per_m3 density;

      quan::force::N weight()
      {
         quan::volume::m3 volume = length * width * height;
         quan::mass::kg mass = density * volume;
         return mass * quan::acceleration::g;
      }
   };
//source = <quan_matters/examples/doc/quan_box.cpp>

Ease of use

When using struct Box, care must be taken over converting between quantities with different conversion factors. The programmer must provide any scaling required...

   Box box;
   double length;
   std::cin >> length;                 // Assume input arrives in millimeters.
   box.length = length * 1000;         // Programmer error!

struct Quan_box understands the concept of conversion factors and automates scaling, relieving the programmer of this chore..

   Quan_box quan_box;
   quan::length::mm length;	 
   std::cin >> length;                // Quan enforces the millimeters type.
   quan_box.length = length;          // Scaling conversion is performed
                                      // automatically by the type.

   // A fixed_quantity can handle conversions of any complexity...
   quan::velocity::m_per_s v1;        // metres per second
   std::cin >> v1;  
   quan::velocity::mi_per_hr v2 = v1; // miles per hour
                                      // scaling conversion is part of the Archetype.

Error detection

A physical quantity must conform to the rules of dimensional analysis. The built-in types cannot enforce these rules:

   // calculate an acceleration
   double initial_velocity = 1;
   double final_velocity = 2;
   double time = 0.5;
   double acceleration 
       = final_velocity - initial_velocity / time;  // Programmer error...
   // ... undetected by the ompiler and time consuming to find manually!

Replacing the built-in types in the above example, by a fixed_quantity that enforces the rules of dimensional analysis, The C++ compiler catches the error at compile time:

   // calculate an acceleration
   quan::velocity::m_per_s      initial_velocity(1);
   quan::velocity::m_per_s      final_velocity(2);
   quan::time::s                time(0.5);
   quan::acceleration::m_per_s2 acceleration 
      = final_velocity - initial_velocity / time;  // Programmer error ... 
   // caught by the compiler!

Using a fixed_quantity helps to clarify, quickly identify, and pinpoint dimensional analysis errors in the source code.

Portable, Typesafe I/O

Quan represents physical quantities in a standardised textual format, so stream input and output are predictable, repeatable, and can be shared across applications. The enforcement of a standardised format also provides typesafety for user input.


Quan Index