mi32/uom.h

Go to the documentation of this file.

/**
 * \file uom.h <mi32/uom.h>
 * \brief UOM (Unit of Measure) system definitions
 *
 * \if NODOC
 * $Id: uom.h_v 1.7 2003/09/29 16:57:51 mju Exp $
 *
 * $Log: uom.h_v $
 * Revision 1.7  2003/09/29 16:57:51  mju
 * Add FindUnit variants using only idnum and id.
 *
 * Revision 1.6  2003/09/25 21:29:07  dwilliss
 * Don't capitalize enum any more. Genitor needed it, doxygen doesn't like it.
 *
 * Revision 1.5  2003/09/19 14:05:00  mju
 * Fix doc comments.
 *
 * Revision 1.4  2003/09/17 15:22:22  dwilliss
 * Fixed operator== and operator!= to return bool (was unspecified)
 *
 * Revision 1.3  2003/09/17 13:49:18  mju
 * Add ==/!= for unit.
 *
 * Revision 1.2  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.1  2003/09/05 17:09:12  mju
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_MI32_UOM_H
#define  INC_MI32_UOM_H

#ifndef  INC_MI32_IDENTIFIER_H
#include <mi32/identifier.h>
#endif

#ifndef  INC_MI32_MISTRING_H
#include <mi32/mistring.h>
#endif

#ifndef  INC_MI32_MILIST_H
#include <mi32/milist.h>
#endif

#ifdef GEOMDLL
   #define CLASSLIBEXPORT MI_DLLCLASSEXPORT
#else
   #define CLASSLIBEXPORT MI_DLLCLASSIMPORT
#endif

namespace UOM {

#ifndef GENERATING_DOXYGEN_OUTPUT
class SYSTEM;
class MEASURE;
class UNIT;
class CONVERTER;
class MEASURE_PRIV;
class UNIT_PRIV;
class CONVERTER_PRIV;
#endif // GENERATING_DOXYGEN_OUTPUT

//-------------------------------------------------------------------------------------------------------------------

//! Single unit container.
//! Normally a UNIT instance is obtained using one of the MEASURE::FindUnit() or GetBaseUnit() methods.
class CLASSLIBEXPORT UNIT {
   public:

      enum NAMEUSAGE {
         NAMEUSAGE_Singular,
         NAMEUSAGE_Plural
         };

      //! Default constructor.
      UNIT (
         );

      //! Copy constructor.
      UNIT (
         const UNIT& rhs
         );

      #ifndef GENERATING_DOXYGEN_OUTPUT
      //! Internal constructor.
      UNIT (
         UNIT_PRIV *pPriv
         );
      #endif // GENERATING_DOXYGEN_OUTPUT

      //! Destructor.
      ~UNIT (
         );

      //! Assignment.
      UNIT& operator= (
         const UNIT& rhs
         );

      //! Convert value in base unit to this unit (numeric).
      double ConvertFromBase (
         double inval
         ) const;

      //! Convert value in base unit to this unit (string).
      void ConvertFromBase (
         double inval,
         MISTRING& outstr
         ) const;

      //! Convert numeric value in this unit to base unit.
      double ConvertToBase (
         double inval
         ) const;

      //! Convert string value in this unit to base unit.
      double ConvertToBase (
         const MISTRING& instr
         ) const;

      //! Get factor A in conversion formula.
      double GetFactorA (
         ) const;

      //! Get factor B in conversion formula.
      double GetFactorB (
         ) const;

      //! Get factor C in conversion formula.
      double GetFactorC (
         ) const;

      //! Get identifer list for unit.
      const IDENTIFIERLIST& GetIdList (
         ) const;

      //! Get MicroImages unit identification number.
      int GetIdNum (
         ) const;

      //! Get measure unit applies to.
      const MEASURE& GetMeasure (
         ) const;

      //! Get unit name.
      const MISTRING& GetName (
         NAMEUSAGE nameusage              //!< Usage name is for
         ) const;

      //! Get unit symbol.
      const MISTRING& GetSymbol (
         ) const;

      //! Determine if equal.
      bool IsEqual (
         const UNIT& rhs
         ) const;

      //! Determine if unit requires a string representation.
      //! @return true if string, false if not.
      bool IsString (
         ) const;

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      UNIT_PRIV *m_pPriv;
      friend class MEASURE_PRIV;
      #endif // GENERATING_DOXYGEN_OUTPUT

   };

//! Equality.
inline bool operator== (
   const UNIT& lhs,
   const UNIT& rhs
   ) { return (lhs.IsEqual(rhs)); }

//! Inequality.
inline bool operator!= (
   const UNIT& lhs,
   const UNIT& rhs
   ) { return (!lhs.IsEqual(rhs)); }

/*
#if defined(WIN32) && !defined(GEOMDLL) && !defined(NODLLLINKAGE)
#pragma warning(disable:4231)
extern template class CLASSLIBEXPORT MILIST<UNIT>;    //! Template instantiation
#pragma warning(default:4231)
#endif
*/
typedef MILIST<UNIT> UNITLIST;


//-------------------------------------------------------------------------------------------------------------------
//! Measure container.
//! Normally one of the UOM::SYSTEM::FindMeasure() methods is used obtain a MEASURE instance.
class CLASSLIBEXPORT MEASURE {
   public:

      //! Enumeration of measure types.
      //! Invariant, may be saved in files by number.
      //! Same as codes used in MicroImages codespace.
      enum TYPE {
         TYPE_Area =                   1,    //!< Area [m²]
         TYPE_Length =                 2,    //!< Length [meter, m]
         TYPE_Distance =               TYPE_Length,
         TYPE_PlaneAngle =             3,    //!< Plane angle [radian, rad]
         TYPE_Time =                   4,    //!< Time [second, s]
         TYPE_Temperature =            5,    //!< Temperature [kelvin, K]
         TYPE_Volume =                 6,    //!< Volume [m³]
         TYPE_Mass =                   7,    //!< Mass [kilogram, kg]
         TYPE_Current =                8,    //!< Electric current [ampere, A]
         TYPE_Amount =                 9,    //!< Amount of substance [mole, mol]
         TYPE_LuminousIntensity =      10,   //!< Luminous intensity [candela, cd]
         TYPE_SolidAngle =             11,   //!< Solid angle [steradian, sr]
         TYPE_Velocity =               12,   //!< Velocity [m/s]
         TYPE_Acceleration =           13,   //!< Acceleration [m/s²]
         TYPE_VolumetricFlowRate =     14,   //!< Volumetric flow rate [M³/s]
         TYPE_MassFlowRate =           15,   //!< Mass flow rate [kg/s]
         TYPE_WaveNumber =             16,   //!< Wave number [1/m]
         TYPE_Density =                17,   //!< Density [kg/m³]
         TYPE_SpecificVolume =         18,   //!< Specific volume [m³/kg]
         TYPE_CurrentDensity =         19,   //!< Current density [A/m²]
         TYPE_MagneticFieldStrength =  20,   //!< Magnetic field strength [A/m]
         TYPE_Concentration =          21,   //!< Concentration [mol/m³]
         TYPE_Luminance =              22,   //!< Luminance [cd/m²]
         TYPE_Frequency =              23,   //!< Frequency [hertz, Hz]
         TYPE_Force =                  24,   //!< Force [newton, N]
         TYPE_Pressure =               25,   //!< Pressure, stress [pascal, Pa]
         TYPE_Energy =                 26,   //!< Energy, work, quantity of heat [joule, J]
         TYPE_Power =                  27,   //!< Power, radiant flux [watt, W]
         TYPE_ElectricCharge =         28,   //!< Electric charge [coulomb, C]
         TYPE_ElectricPotential =      29,   //!< Electric potential [volt, V]
         TYPE_Capacitance =            30,   //!< Capacitance [farad, F]
         TYPE_ElectricResistance =     31,   //!< Electric resistance [ohm, Omega]
         TYPE_ElectricConductance =    31,   //!< Electric conductance [siemens, S]
         TYPE_MagneticFlux =           33,   //!< Magentic flux [weber, Wb]
         TYPE_MagneticFluxDensity =    34,   //!< Magnetic flux density [tesla, T]
         TYPE_Inductance =             35,   //!< Inductance [henry, H]
         TYPE_LuminousFlux =           36,   //!< Luminous flux [lumen, lm]
         TYPE_RadionuclideActivity =   37,   //!< Activity of radionuclide [becquerel, Bq]
         TYPE_AbsorbedDose =           38,   //!< Absorbed dose [gray, Gy]
         TYPE_DoseEquivalent =         39,   //!< Dose equivalent [sievert, Sv]
         TYPE_DynamicViscosity =       40,   //!< Dynamic viscosity [Pa·s]
         TYPE_MomentOfForce =          41,   //!< Moment of force [N·m]
         TYPE_SurfaceTension =         42,   //!< Surface tension [N/m]
         TYPE_Irradiance =             43,   //!< Irradiance, heat flux density [W/m²]
         TYPE_Entropy =                44,   //!< Entropy, heat capacity [J/K]
         TYPE_SpecificHeatCapacity =   45,   //!< Specific heat capacity [J/(kg·K)]
         TYPE_SpecificEnergy =         46,   //!< Specific energy [J/kg]
         TYPE_ThermalConductivity =    47,   //!< Thermal conductivity [W/(m·K)]
         TYPE_EnergyDensity =          48,   //!< Energy density [J/m³]
         TYPE_ElectricFieldStrength =  49,   //!< Electric field strength [V/m]
         TYPE_ElectricChargeDensity =  50,   //!< Electric charge density [C/m³]
         TYPE_ElectricFluxDensity =    51,   //!< Electric flux density [C/m²]
         TYPE_Permitivity =            52,   //!< Permitivity [F/m]
         TYPE_Permeability =           53,   //!< Permeability [H/m]
         TYPE_MolarEnergy =            54,   //!< Molar energy [J/mol]
         TYPE_MolarEntropy =           55,   //!< Molar entropy [J/(mol·K)]
         TYPE_Exposure =               56,   //!< Exposure (X and gamma rays) [C/kg]
         TYPE_AbsorbedDoseRate =       57,   //!< Absorbed dose rate [Gy/s]
         TYPE_AngularVelocity =        58,   //!< Angular velocity [rad/s]
         TYPE_AngularAcceleration =    59,   //!< Angular acceleration [rad/s²]
         TYPE_RadiantIntensity =       60,   //!< Radiant intensity [W/sr]
         TYPE_Radiance =               61,   //!< Radiance [W/m²·sr]
         TYPE_Scale =                  62,   //!< Scale (unit/unit)
         TYPE_Image =                  63,   //!< Image (pixel)

         TYPE_LASTNONDATE =            63,   //!< Last measure type other than date

         TYPE_Date =                   99,   //!< Date, possibly formatted
         TYPE_None =                   255
         };

      //! Default constructor, constructs instance with TYPE_None.
      MEASURE (
         );

      //! Copy constructor.
      MEASURE (
         const MEASURE& rhs
         );

      #ifndef GENERATING_DOXYGEN_OUTPUT
      //! Internal constructor.
      MEASURE (
         MEASURE_PRIV *pPriv
         );
      #endif // GENERATING_DOXYGEN_OUTPUT

      //! Destructor.
      ~MEASURE (
         );

      //! Assignment.
      MEASURE& operator= (
         const MEASURE& rhs
         );

      //! Find unit using MicroImages identification code.
      //! @return true if found, false if not.
      bool FindUnit (
         int micode,                      //!< MicroImages identification code
         UNIT& unitret                    //!< Unit returned if found
         ) const;

      //! Find unit using IDENTIFIER.
      //! @return true if found, false if not.
      bool FindUnit (
         const IDENTIFIER& identifier,    //!< Identifier
         UNIT& unitret                    //!< Unit returned if found
         ) const;

      //! Find unit using name.
      //! Searches all 'string' identifiers, localized names, localized symbols.
      //! @return true if found, false if not.
      bool FindUnit (
         const MISTRING& name,            //!< Unit name
         UNIT& unitret                    //!< Unit returned if found
         ) const;
         
      //! Get base unit for measure.
      //! @return Reference to base unit.
      const UNIT& GetBaseUnit (
         ) const;

      //! Get identifer list for measure.
      const IDENTIFIERLIST& GetIdList (
         ) const;

      //! Get name of measure.
      const MISTRING& GetName (
         ) const;

      //! Get measure type enumeration.
      TYPE GetType (
         ) const;

      //! Get unit list for measure.
      const UNITLIST& GetUnitList (
         ) const;

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      MEASURE_PRIV *m_pPriv;
      #endif // GENERATING_DOXYGEN_OUTPUT

   };


//! Equality.
inline bool operator== (
   const MEASURE& lhs,
   const MEASURE& rhs
   ) { return (lhs.GetType() == rhs.GetType()); }

//! Inequality.
inline bool operator!= (
   const MEASURE& lhs,
   const MEASURE& rhs
   ) { return (lhs.GetType() != rhs.GetType()); }

/*
#if defined(WIN32) && !defined(GEOMDLL) && !defined(NODLLLINKAGE)
#pragma warning(disable:4231)
extern template class CLASSLIBEXPORT MILIST<MEASURE>;    //! Template instantiation
#pragma warning(default:4231)
#endif
*/
typedef MILIST<MEASURE> MEASURELIST;

//-------------------------------------------------------------------------------------------------------------------

//! System methods.
class CLASSLIBEXPORT SYSTEM {
   public:

      //! Find measure instance by IDENTIFIER.
      //! @return true if found, false if not.
      static bool FindMeasure (
         const IDENTIFIER& identifier,    //!< Identifier
         MEASURE& measure                 //!< Measure returned if found
         );

      //! Find measure instance by TYPE.
      //! @return true if found, false if not.
      static bool FindMeasure (
         MEASURE::TYPE type,              //!< Measure type
         MEASURE& measure                 //!< Measure returned if found
         );

      //! Find unit using MicroImages composite measure/unit identification number.
      //! Code is in the form 256 * MeasureNum + UnitNum;
      //! @return true if found, false if not.
      static bool FindUnit (
         int micode,                      //!< MicroImages identification code
         UNIT& unitret                    //!< Unit returned if found
         );
         
      //! Find unit using TYPE and MicroImages unit identification number.
      //! @return true if found, false if not.
      static bool FindUnit (
         MEASURE::TYPE type,              //!< Measure type
         int micode,                      //!< MicroImages identification code
         UNIT& unitret                    //!< Unit returned if found
         );
         
      //! Find unit using IDENTIFIER.
      //! @return true if found, false if not.
      static bool FindUnit (
         const IDENTIFIER& identifier,    //!< Identifier
         UNIT& unitret                    //!< Unit returned if found
         );
         
      //! Find unit using TYPE and IDENTIFIER.
      //! @return true if found, false if not.
      static bool FindUnit (
         MEASURE::TYPE type,              //!< Measure type
         const IDENTIFIER& identifier,    //!< Identifier
         UNIT& unitret                    //!< Unit returned if found
         );
         
      //! Find unit using TYPE and name.
      //! Searches all 'string' identifiers, localized names, localized symbols.
      //! @return true if found, false if not.
      static bool FindUnit (
         MEASURE::TYPE type,              //!< Measure type
         const MISTRING& name,            //!< Unit name
         UNIT& unitret                    //!< Unit returned if found
         );
         
      //! Get list of MEASUREs.
      //! Will not include entry for TYPE_None.
      static const MEASURELIST& GetMeasureList (
         );

      //! Initialize unit of measure system.
      //! Automatically called by application initialization code.
      static ERRVALUE Initialize ();
   };


//-------------------------------------------------------------------------------------------------------------------

class CLASSLIBEXPORT CONVERTER {
   public:

      //! Default constructor.
      CONVERTER (
         );

      //! Copy constructor.
      CONVERTER (
         const CONVERTER& rhs
         );

      //! Identity constructor.
      CONVERTER (
         const MEASURE& measure
         );

      //! Destructor.
      ~CONVERTER ();

      //! Assignment.
      CONVERTER& operator= (
         const CONVERTER& rhs
         );

      //! Convert numeric value from source unit to target unit.
      //! If either source or target unit requires a string representation the original value will be returned.
      //! @return Converted value.
      double ConvertForward (
         double value                     //!< Value in source unit to convert
         ) const;

      //! Convert string in source unit to numeric value in target unit.
      //! If target unit requires a string representation an error will be returned.
      ERRVALUE ConvertForward (
         const MISTRING& instr,           //!< String in source unit to convert
         double& outval                   //!< Value in target unit returned
         ) const;
         
      //! Convert numeric value in source unit to string in target unit.
      //! If source unit requires a string representation an error will be returned.
      ERRVALUE ConvertForward (
         double inval,                    //!< Value in source unit to convert
         MISTRING& outstr                 //!< String in target unit returned
         ) const;
         
      //! Convert string in source unit to string in target unit.
      ERRVALUE ConvertForward (
         const MISTRING& instr,           //!< String in source unit to convert
         MISTRING& outstr                 //!< String in target unit returned
         ) const;
         
      //! Convert numeric value from target unit to source unit.
      //! If either target or source unit requires a string representation the original value will be returned.
      //! @return Converted value.
      double ConvertInverse (
         double value                     //!< Value in target unit to convert
         ) const;

      //! Convert string in target unit to numeric value in source unit.
      //! If source unit requires a string representation an error will be returned.
      ERRVALUE ConvertInverse (
         const MISTRING& instr,           //!< String in target unit to convert
         double& outval                   //!< Value in source unit returned
         ) const;
         
      //! Convert numeric value in target unit to string in source unit.
      //! If target unit requires a string representation an error will be returned.
      ERRVALUE ConvertInverse (
         double inval,                    //!< Value in target unit to convert
         MISTRING& outstr                 //!< String in source unit returned
         ) const;
         
      //! Convert string in target unit to string in source unit.
      ERRVALUE ConvertInverse (
         const MISTRING& instr,           //!< String in target unit to convert
         MISTRING& outstr                 //!< String in source unit returned
         ) const;
         
      //! Get measure associated with converter.         
      const MEASURE& GetMeasure (
         ) const;

      //! Get scale multiplication value from source to target.
      double GetScale (
         ) const;

      //! Get source unit.
      const UNIT& GetSourceUnit (
         ) const;

      //! Get target unit.
      const UNIT& GetTargetUnit (
         ) const;

      //! Read source unit from INI file.
      //! Target unit will be left unchanged.
      void IniReadSource (
         INIHANDLE IniHandle,
         const char *IniGroup,
         const char *IniName,
         int micode = 0                      //!< Default unit code
         );

      //! Read target unit from INI file.
      //! Source unit will be left unchanged.
      void IniReadTarget (
         INIHANDLE IniHandle,
         const char *IniGroup,
         const char *IniName,
         int micode = 0                      //!< Default unit code
         );

      //! Write source unit code to INI file.
      void IniWriteSource (
         INIHANDLE IniHandle,
         const char *IniGroup,
         const char *IniName
         ) const;

      //! Write target unit code to INI file.
      void IniWriteTarget (
         INIHANDLE IniHandle,
         const char *IniGroup,
         const char *IniName
         ) const;

      //! Set source unit.
      //! If the current measure is of TYPE_None it will be set to the measure of the specified unit.
      //! Otherwise, an error will be returned if the unit does not refer to the current measure.
      ERRVALUE SetSourceUnit (
         const UNIT& SourceUnit
         );

      //! Set target unit.
      //! If the current measure is of TYPE_None it will be set to the measure of the specified unit.
      //! Otherwise, an error will be returned if the unit does not refer to the current measure.
      ERRVALUE SetTargetUnit (
         const UNIT& TargetUnit
         );

      //! Set both source and target units.
      //! An error will be returned if the specified units do not refer to the same MEASURE.
      ERRVALUE SetUnits (
         const UNIT& SourceUnit,
         const UNIT& TargetUnit
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      CONVERTER_PRIV *m_pPriv;
      void GetExclusive();
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

//-------------------------------------------------------------------------------------------------------------------
}; //! End namespace UOM


typedef  UOM::MEASURE::TYPE   UNIT_TYPE;

#define  UNIT_TYPE_Constant                  0     //!< Constants and unitless database fields
#define  UNIT_TYPE_Area                      UOM::MEASURE::TYPE_Area
#define  UNIT_TYPE_Length                    UOM::MEASURE::TYPE_Length
#define  UNIT_TYPE_Distance                  UOM::MEASURE::TYPE_Distance
#define  UNIT_TYPE_PlaneAngle                UOM::MEASURE::TYPE_PlaneAngle
#define  UNIT_TYPE_Time                      UOM::MEASURE::TYPE_Time
#define  UNIT_TYPE_Volume                    UOM::MEASURE::TYPE_Volume
#define  UNIT_TYPE_Velocity                  UOM::MEASURE::TYPE_Velocity
#define  UNIT_TYPE_Acceleration              UOM::MEASURE::TYPE_Acceleration
#define  UNIT_TYPE_AngularVelocity           UOM::MEASURE::TYPE_AngularVelocity
#define  UNIT_TYPE_Date                      UOM::MEASURE::TYPE_Date
#define  UNIT_TYPE_None                      UOM::MEASURE::TYPE_None


//---------------------------------------------------------------------------------------------------------------------
//!      Commmon MicroImages numeric Unit identifiers

#define  UNIT_Area_SquareMeter         0
#define  UNIT_Area_SquareMeters        0
#define  UNIT_Area_SquareKilometer     3
#define  UNIT_Area_SquareKilometers    3
#define  UNIT_Area_SquareMillimeter    2
#define  UNIT_Area_SquareMillimeters   2

#define  UNIT_Length_Meter             0
#define  UNIT_Length_Kilometer         3
#define  UNIT_Length_Centimeter        1
#define  UNIT_Length_Millimeter        2
#define  UNIT_Length_Micrometer        8
#define  UNIT_Length_Nanometer         9
#define  UNIT_Length_Foot              4
#define  UNIT_Length_Inch              6

#define  UNIT_Distance_Meters          UNIT_Length_Meter
#define  UNIT_Distance_Kilometers      UNIT_Length_Kilometer
#define  UNIT_Distance_Centimeters     UNIT_Length_Centimeter
#define  UNIT_Distance_Millimeters     UNIT_Length_Millimeter
#define  UNIT_Distance_Micrometers     UNIT_Length_Micrometer
#define  UNIT_Distance_Nanometers      UNIT_Length_Nanometer
#define  UNIT_Distance_Feet            UNIT_Length_Foot
#define  UNIT_Distance_Inches          UNIT_Length_Inch

#define  UNIT_PlaneAngle_Degree        0
#define  UNIT_PlaneAngle_Degrees       0
#define  UNIT_PlaneAngle_Radian        1
#define  UNIT_PlaneAngle_Radians       1

#define  UNIT_Time_Second              0
#define  UNIT_Time_Seconds             0
#define  UNIT_Time_Millisecond         6
#define  UNIT_Time_Milliseconds        6
#define  UNIT_Time_Microsecond         7
#define  UNIT_Time_Microseconds        7

#define  UNIT_Volume_CubicMeter        0
#define  UNIT_Volume_CubicMeters       0

#undef   CLASSLIBEXPORT

#endif   //!< INC_MI32_UOM_H

---