units.h

Go to the documentation of this file.

/* Author(s) :    Francois Mauger <mauger@lpccaen.in2p3.fr>
 * Creation date: 2010-03-18
 * Last modified: 2015-10-18
 *
 * License: GPL3
 *
 * Description:
 *
 *   Utilities for units based on the CLHEP library's implementation
  *
 */
#ifndef DATATOOLS_UNITS_H
#define DATATOOLS_UNITS_H

// Standard Library:
#include <string>
#include <vector>
#include <set>
#include <map>
#include <limits>
#include <list>

// Third party:
// - Boost:
#include <boost/cstdint.hpp>

// This Project:
#include <datatools/exception.h>
#include <datatools/i_tree_dump.h>

#ifndef Q_MOC_RUN
#include <datatools/reflection_interface.h>
#endif // Q_MOC_RUN

namespace datatools {

  namespace units {

    enum power_of_ten {
      YOCTO = -24,
      ZEPTO = -21,
      ATTO  = -18,
      FEMTO = -15,
      PICO  = -12,
      NANO  =  -9,
      MICRO =  -6,
      MILLI =  -3,
      CENTI =  -2,
      DECI  =  -1,
      UNIT_POWER_OF_TEN = 0,
      DECA  =   1,
      HECTO =   2,
      KILO  =   3,
      MEGA  =   6,
      GIGA  =   9,
      TERA  =  12,
      PETA  =  15,
      EXA   =  18,
      ZETTA =  21,
      YOTTA =  24
    };

    double yocto();
    double zepto();
    double atto();
    double femto();
    double pico();
    double nano();
    double micro();
    double milli();
    double centi();
    double deci();
    double deca();
    double hecto();
    double kilo();
    double mega();
    double giga();
    double tera();
    double peta();
    double exa();
    double zetta();
    double yotta();

    double power_of_ten_to_factor(power_of_ten);

    std::string power_of_ten_to_name(power_of_ten);

    std::string power_of_ten_to_symbol(power_of_ten);

    enum power_of_two {
      UNIT_POWER_OF_TWO = 0,
      KIBI = 10,
      MEBI = 20,
      GIBI = 30,
      TEBI = 40,
      PEBI = 50,
      EXBI = 60,
      ZEBI = 70,
      YOBI = 80
    };

    double byte_to_bit_factor();

    static const double bit   = 1.0;
    static const double octet = 8.0 * bit;
    static const double byte  = octet;

    double power_of_two_to_factor(power_of_two);

    std::string power_of_two_to_name(power_of_two);

    std::string power_of_two_to_symbol(power_of_two);

    size_t registered_unit_dimension_labels(std::vector<std::string> & dimension_labels_);

    size_t registered_unit_names(std::vector<std::string> & unit_names_);

    size_t registered_unit_symbols(std::vector<std::string> & unit_symbols_);

    bool is_unit_in_dimension_from(const std::string& unit_id_,
                                   const std::string& unit_dimension_label_);

    double get_unit_in_dimension_from(const std::string& unit_id_,
                                      const std::string& unit_dimension_label_);

    double get_length_unit_from(const std::string& unit_id_);

    double get_surface_unit_from(const std::string&);

    double get_volume_unit_from(const std::string&);

    double get_time_unit_from(const std::string&);

    double get_angle_unit_from(const std::string&);

    double get_solid_angle_unit_from(const std::string&);

    double get_energy_unit_from(const std::string&);

    double get_mass_unit_from(const std::string&);

    double get_pressure_unit_from(const std::string&);

    double get_magnetic_flux_density_unit_from(const std::string&);

    double get_magnetic_field_unit_from(const std::string&);

    double get_electric_field_unit_from(const std::string&);

    double get_electric_potential_unit_from(const std::string&);

    double get_electric_tension_unit_from(const std::string&);

    double get_temperature_unit_from(const std::string&);

    double get_density_unit_from(const std::string&);

    double get_activity_unit_from(const std::string&);

    double get_surface_activity_unit_from(const std::string&);

    double get_volume_activity_unit_from(const std::string&);

    double get_mass_activity_unit_from(const std::string&);

    double get_frequency_unit_from(const std::string&);

    double get_electric_charge_unit_from(const std::string&);

    double get_electric_current_unit_from(const std::string&);

    double get_velocity_unit_from(const std::string&);

    double get_speed_unit_from(const std::string&);



    double get_unit_from(const std::string& unit_type_,
                         const std::string& unit_str_);


    double get_unit(const std::string& unit_str_, bool throw_ = false);

    // const std::vector<std::string>& get_unit_labels_registry();


    bool is_unit_label_valid(const std::string & unit_label_);

    std::string get_default_unit_symbol_from_label(const std::string & unit_label_);


    bool find_unit(const std::string & unit_str_,
                   double & unit_value_,
                   std::string & unit_label_);


    double get_value_with_unit(const std::string& word_);


    bool find_value_with_unit(const std::string & word_,
                              double & value_,
                              std::string & unit_label_,
                              double default_unit_ = std::numeric_limits<double>::quiet_NaN());


    bool parse_value_with_unit(const std::string& word,
                               double& value,
                               std::string& unit_symbol,
                               std::string& unit_label,
                               uint32_t flags = 0);

    class unit
      : public i_tree_dumpable
    {

    public:

      unit();

      unit(const std::string & name_,
           const std::string & dimension_desc_,
           double value_,
           bool SI_main_ = false);

      unit(const std::string & name_,
           const std::string & symbol_,
           const std::string & dimension_desc_,
           double value_,
           bool SI_main_ = false);

      unit(const std::string & name_,
           const std::string & main_symbol_,
           const std::string & alt_symbols_,
           const std::string & dimension_desc_,
           double value_,
           bool SI_main_ = false);

      virtual ~unit();

      bool is_valid() const;

      void reset();

      bool has_name() const;

      const std::string & get_name() const;

      unit & set_name(const std::string &);

      unit & add_symbol(const std::string & symbol_, bool main_ = false);

      bool has_symbol(const std::string & symbol_) const;

      bool match(const std::string & id_) const;

      const std::set<std::string> & get_symbols() const;

      bool has_main_symbol() const;

      const std::string & get_main_symbol() const;

      unit & set_main_symbol(const std::string &);

      bool has_dimension_label() const;

      const std::string & get_dimension_label() const;

      unit & set_dimension_label(const std::string &);

      bool has_dimension_meta() const;

      const std::string & get_dimension_meta() const;

      unit & set_dimension_meta(const std::string &);

      unit & set_dimension_infos(const std::string &);

      bool is_dimension(const std::string &) const;

      bool is_SI_main() const;

      unit & set_SI_main(bool);

      double get_value() const;

      unit & set_value(double);

      operator double() const;

      const std::string & str() const;

      // Implement a manipulator for "cout << meter(23.1) << endl;" printing "0.0231" ???
      // std::ostream & operator()(std::ostream & out_, double x_) const;

      virtual void tree_dump(std::ostream & out_ = std::clog,
                             const std::string & title_ = "",
                             const std::string & indent_ = "",
                             bool inherit_ = false) const;

    protected:

      void _set_default();

    private:

      std::string           _name_;            
      std::set<std::string> _symbols_;         
      std::string           _main_symbol_;     
      std::string           _dimension_label_; 
      std::string           _dimension_meta_;  
      bool                  _SI_main_;         
      double                _value_;           

    };

    class unit_dimension
      : public i_tree_dumpable
    {

    public:

      enum base_dimension_type {
        BD_INVALID              =  0,
        BD_MASS                 =  1, // [M]
        BD_LENGTH               =  2, // [L]
        BD_TIME                 =  3, // [T]
        BD_ELECTRIC_CURRENT     =  4, // [I]
        BD_TEMPERATURE          =  5, // [theta]
        BD_ABSOLUTE_TEMPERATURE =  5, // [theta]
        BD_AMOUNT               =  6, // [N]
        BD_AMOUNT_OF_SUBSTANCE  =  6, // [N]
        BD_LUMINOUS_INTENSITY   =  7, // [J]
        BD_PROCEDURE_DEFINED    =  8, // [?] For "arbitrary/procedure defined" units
        BD_LAST                 =  BD_PROCEDURE_DEFINED + 1
      };

      static std::string base_dimension_to_symbol(base_dimension_type);

      static base_dimension_type symbol_to_base_dimension(const std::string &);

      static std::string base_dimension_to_label(base_dimension_type);

      static base_dimension_type label_to_base_dimension(const std::string &);

      static bool validate_dimension_label(const std::string & name_);

      unit_dimension();

      unit_dimension(const std::string & label_,
                     const std::string & default_unit_symbol_);

      virtual ~unit_dimension();

      bool is_valid() const;

      void reset();

      bool has_label() const;

      unit_dimension & set_label(const std::string &);

      const std::string & get_label() const;

      bool has_unit(const std::string & unit_name_) const;

      unit_dimension & add_unit(const std::string & unit_name_,
                                bool default_unit_ = false);

      void remove_unit(const std::string & unit_name_);

      const std::set<std::string> & get_unit_names() const;

      bool has_default_unit() const;

      unit_dimension & set_default_unit_name(const std::string & unit_name_);

      const std::string & get_default_unit_name() const;

      bool has_dimensional_powers() const;

      void reset_dimensional_powers();

      bool decode_dimensional_powers(const std::string & word_);

      void encode_dimensional_powers(std::string & word_) const;

      bool is_dimensionless() const;

      bool match_dimensional_powers(const unit_dimension & ud_) const;

      virtual void tree_dump(std::ostream & out_ = std::clog,
                             const std::string & title_ = "",
                             const std::string & indent_ = "",
                             bool inherit_ = false) const;

    protected:

      void _set_default();

    private:

      std::string           _label_;                 
      std::set<std::string> _unit_names_;            
      std::string           _default_unit_name_;     
      int                   _dimensional_powers_[9]; 

    };

    class registry
      : public i_tree_dumpable
    {

    public:

      enum init_flag_type {
        NO_STANDARD_UNITS = 0x1
      };

      typedef std::map<std::string, unit> unit_dict_type;

      typedef std::map<std::string, const unit *> symbol_dict_type;

      typedef std::map<std::string, unit_dimension> dimension_dict_type;

      registry(uint32_t flags_ = 0);

      ~registry();

      void registration(const unit & unit_, bool default_in_dimension_ = false);

      void unregistration(const std::string & unit_name_);

      bool has_unit(const std::string & unit_name_) const;

      const unit & get_unit(const std::string & unit_name_) const;

      bool has_symbol(const std::string & unit_symbol_) const;

      bool has_unit_from_any(const std::string & unit_label_) const;

      const unit & get_unit_from_symbol(const std::string & unit_symbol_) const;

      const unit & get_unit_from_any(const std::string & unit_id_) const;

      bool has_dimension(const std::string & dimension_label_) const;

      const unit_dimension & get_dimension(const std::string & dimension_label_) const;

      void clear();

      const unit_dict_type & get_units() const;

      const symbol_dict_type & get_symbols() const;

      const dimension_dict_type & get_dimensions() const;

      bool build_ordered_unit_symbols(const std::string & dimension_label_,
                                      std::list<std::string> & symbols_) const;

      void register_standard_units();

      virtual void tree_dump(std::ostream & out_ = std::clog,
                             const std::string & title_ = "",
                             const std::string & indent_ = "",
                             bool inherit_ = false) const;

    protected:

      unit & _grab_unit(const std::string & unit_name_);

      unit_dimension & _grab_dimension(const std::string & dimension_label_);

    private:

      unit_dict_type      _units_;      
      symbol_dict_type    _symbols_;    
      dimension_dict_type _dimensions_; 

    public:

      static registry & system_registry();

      static const registry & const_system_registry();

    private:

      static registry & _access_system_registry_();

    };

  } // end of namespace units

} // end of namespace datatools

#ifndef Q_MOC_RUN
// Activate reflection layer:
DR_TYPE_INIT(::datatools::units::power_of_ten)
#endif // Q_MOC_RUN

#define DT_THROW_BAD_UNIT(UnitType,UnitSymbol)                          \
  DT_THROW_IF(true,std::logic_error,                                    \
              "Invalid '" << UnitType << "' unit for symbol '" << UnitSymbol << "' !")


#endif // DATATOOLS_UNITS_H

// Local Variables: --
// mode: c++ --
// c-file-style: "gnu" --
// tab-width: 2 --
// End: --