Class convert_units (o2scl)

O2scl : Class List

template<class fp_t = double>
class convert_units

Convert units.

Allow the user to convert between two different units after specifying a conversion factor. This class will also automatically combine two conversion factors to create a new unit conversion (but it cannot combine more than two).

Conversions are performed by the convert() function. The run-time unit cache is initially filled with hard-coded conversions, and convert() searches this cache is searched for the requested conversion first. If this is successful, then the conversion factor is returned and the conversion is added to the cache. If a conversion is not found, then it is computed.

Example: 

convert_units cu;
cout << "A solar mass is " << cu.convert("Msun","g",1.0) 
<< " g. " << endl;

An object of this type is created by o2scl_settings (of type lib_settings_class) for several unit conversions used internally in .

Todo

In class convert_units:

  • (Future) Add G=1.

Note

Combining two conversions allows for some surprising apparent contradictions from numerical precision errors. If there are two matching unit conversion pairs which give the same requested conversion factor, then one can arrange a situation where the same conversion factor is reported with slightly different values after adding a related conversion to the table. One way to fix this is to force the class not to combine two conversions by setting combine_two_conv to false. Alternatively, one can ensure that no conversion is necessary by manually adding the desired combination conversion to the cache after it is first computed.

Note

Only the const functions, convert_const and convert_ret_const are guaranteed to be thread-safe, since they are not allowed to update the unit cache.

Note

This class is designed to allow for higher-precision conversions, but this is experimental. Also, not all of the unit conversions are known to high precision.

Unit data and associated objects

typedef std::map<std::string, unit_t, std::less<std::string>>::iterator miter

The iterator type.

typedef std::map<std::string, unit_t, std::less<std::string>>::const_iterator mciter

The const iterator type.

std::map<std::string, unit_t, std::less<std::string>> mcache

The cache where unit conversions are stored.

std::vector<std::string> prefixes

SI prefix labels.

std::vector<std::string> prefix_names

SI prefix labels.

std::vector<fp_t> prefix_facts

SI prefix factors.

std::vector<der_unit> SI

SI-like units which allow prefixes.

Set in constructor.

static const size_t n_prefixes = 21

Number of SI prefixes.

std::vector<der_unit> other

Other units which do not allow prefixing.

Set in constructor.

Flags for natural units

bool c_is_1
bool hbar_is_1
bool kb_is_1
bool G_is_1

Internal functions [protected]

find_constants<fp_t> fc

The associated o2scl::find_constants object.

inline void set_vars(fp_t m, fp_t k, fp_t s, fp_t K, fp_t A, fp_t mol, fp_t cd, std::map<std::string, fp_t> &vars, bool test_vars = false) const

Set variables for the calculator object for convert_calc()

inline int convert_internal(std::string from, std::string to, fp_t val, fp_t &converted, fp_t &factor, bool &new_conv)

The internal conversion function which tries the cache first and, if that failed, tries to compute the conversion.

This function returns 0 if the conversion was successful. If the conversion fails and err_on_fail is true, then the error handler is called. If the conversion fails and err_on_fail is false, then the value o2scl::exc_enotfound is returned.

The public conversion functions in this class are basically just wrappers around this internal function.

inline int convert_internal_const(std::string from, std::string to, fp_t val, fp_t &converted, fp_t &factor, bool &new_conv) const

The internal conversion function which tries the cache first and, if that failed, tries to compute the conversion (const version)

This function returns 0 if the conversion was successful. If the conversion fails and err_on_fail is true, then the error handler is called. If the conversion fails and err_on_fail is false, then the value o2scl::exc_enotfound is returned.

The public conversion functions in this class are basically just wrappers around this internal function.

inline int convert_cache(std::string from, std::string to, fp_t val, fp_t &converted, fp_t &factor) const

Attempt to construct a conversion from the internal unit cache.

This function returns 0 if the conversion was successful and o2scl::exc_efailed otherwise. This function does not call the error handler.

inline convert_units()

Create a unit-conversion object.

inline virtual ~convert_units()
inline void add_unit(const der_unit &d)

Add a user-defined unit.

inline void del_unit(std::string label)

Remove a non-SI unit.

inline void set_natural_units(bool c_is_one = true, bool hbar_is_one = true, bool kb_is_one = true)

Set natural units.

inline void test_unique()

Test to make sure all units are unique.

inline void print_units(std::ostream &out)

Print the units in the data base.

inline void print_units_cout()

Print units to std::cout.

inline void get_curr_unit_list(std::vector<std::string> &vs) const

Get the current unit list as an array of strings.

inline int find_nothrow(std::string name, std::string unit, std::vector<typename find_constants<fp_t>::const_entry> &matches, bool use_regex = false)

Search for constants matching name with unit unit (possibly empty) and store matches in indexes.

inline void find_print(std::string name, std::string unit, size_t prec, bool use_regex)

Search for constants matching name with unit unit and output result(s) with precision prec. 

This function can fail, if either the requested precision
is larger than machine precision or if the argument \c name
does not match a constant in the library. In either case,
this function prints a short message to std::cout explaining
the failure.
inline fp_t find_unique(std::string name, std::string unit, bool use_regex = false)

Find a unique match and return the numerical value.

inline int convert_calc(std::string from, std::string to, fp_t val, fp_t &converted, fp_t &factor)

Convert units, possibly using constants from the internal o2scl::find_constants object.

inline int convert_calc_hck(std::string from, std::string to, fp_t val, fp_t &converted, fp_t &factor) const

Convert units, taking into account conversions which are allowed by setting hbar, c, or kB to 1.

This function is also useful as a const version of convert_calc() .

User settings

int verbose

Verbosity (default 0)

bool err_on_fail

If true, throw an exception when a conversion fails (default true)

bool combine_two_conv

If true, allow combinations of two conversions (default true)

Basic usage

inline virtual fp_t convert(std::string from, std::string to, fp_t val)

Return the value val after converting using units from and to.

inline virtual fp_t convert_const(std::string from, std::string to, fp_t val) const

Return the value val after converting using units from and to (const version)

Conversions which don’t throw exceptions

inline virtual int convert_ret(std::string from, std::string to, fp_t val, fp_t &converted)

Return the value val after converting using units from and to, returning a non-zero value on failure.

inline virtual int convert_ret_const(std::string from, std::string to, fp_t val, fp_t &converted) const

Return the value val after converting using units from and to, returning a non-zero value on failure (const version)

Manipulate unit cache

inline int remove_cache(std::string from, std::string to)

Remove a unit conversion from the cache.

If either the forward or reverse conversions are found, they are removed from the cache. If neither is found, the error handler is called, unless err_on_fail is false, in which case o2scl::exc_enotfound is returned.

inline int is_in_cache(std::string from, std::string to) const

Test if a unit conversion is in the cache.

The possible return values are as follows:

  • 0: neither the forward nor the reverse conversion are in the cache

  • 1: only the forward conversion is in the cache

  • 2: only the reverse conversion is in the cache

  • 3: both the forward and reverse conversions are in the cache

inline void clear_cache()

Clear the cache completely.

inline void insert_cache(std::string from, std::string to, fp_t conv)

Manually insert a unit conversion into the cache.

inline void print_cache() const

Print the present unit cache to std::cout.

template<class test_mgr_t>
inline void test_cache_calc(test_mgr_t &t)

Test the cache and the new convert_calc() function.

Note

We make this a template to avoid problems with circular headers.

inline void default_conversions()

Add default conversions.

Where possible, this uses templates from constants.h to define the conversions exactly in the user-specified floating-point type.

Public Types

typedef struct o2scl::convert_units::der_unit_s der_unit

Type of a derived unit.

struct der_unit_s

Type of a derived unit.

Public Members

std::string label

Unit label.

int m

Power of length.

int k

Power of mass.

int s

Power of time.

int K

Power of temperature.

int A

Power of current.

int mol

Power of moles.

int cd

Power of luminous intensity.

fp_t val

Value.

std::string name

Long name.

struct unit_t

The type for caching unit conversions.

Public Members

std::string f

The input unit.

std::string t

The output unit.

fp_t c

The conversion factor.