Units and unit systems

Unit definitions, system registries, conversion, and available-unit lists.

enum class snt::puq::Utype : std::uint8_t

Values:

enumerator NUL: empty flag

enumerator BAS: base units

enumerator LIN: standard unit (linear conversion)

enumerator LOG: logarithmic unit

enumerator TMP: temperature unit

enumerator CST: constant

enumerator CSB: base constant

enumerator QUA: quantity

enumerator CUS: custom unit

enum class snt::puq::SystemType

Values:

enumerator SI: International system of units.

enumerator ESU: Electrostatic CGS system of units.

enumerator GU: Gauss CGS sytem of units.

enumerator EMU: Electromagnetic CGS system of units.

enumerator IU: Imperial units.

enumerator US: United States customary system of units.

enumerator AU: Atomic system of units.

enumerator PU: Planck system of units.

enumerator SRU: Units for special relativity.

enumerator GRU: Units for general relativity.

enumerator GEO: Geometrized units.

enumerator COUNT: Number of units systems.

enumerator NONE: No unit system selected.

using snt::puq::BaseDimensions = std::array<ExponentVariant, Config::num_basedim>

using snt::puq::AllowedPrefixes = std::set<std::string>

using snt::puq::UnitListType = std::unordered_map<std::string, UnitStruct>

using snt::puq::DimensionMapType = std::unordered_map<std::string, DimensionStruct>

const Utype snt::puq::UT_LIN_BAS

const Utype snt::puq::UT_LIN_BAS_CST

const Utype snt::puq::UT_LIN_BAS_TMP

const Utype snt::puq::UT_LIN_TMP

const Utype snt::puq::UT_LIN_CST

const Utype snt::puq::UT_LIN_CSB

const Utype snt::puq::UT_LIN_LOG

const Utype snt::puq::UT_LIN_QUA

const Utype snt::puq::UT_LIN_CUS

const std::unordered_map<std::string, UnitPrefixStruct> snt::puq::UnitPrefixList

const std::vector<std::string> snt::puq::UnitPrefixOrder

std::unordered_map<SystemType, SystemDataType*> snt::puq::SystemMap

Forward definition of the SystemType list.

Map of sytem types and corresponding pointers to the system data structures

std::unordered_map<SystemType, SystemDataType> snt::puq::CustomSystemMap: Map of custom units for each unit system.

std::string snt::puq::table_header(std::string title, std::vector<std::string> header, std::vector<int> width)

inline Utype snt::puq::operator|(Utype lhs, Utype rhs)

Combine two unit-system flags.

Parameters:

lhs – Left-hand operand or flag set.
rhs – Right-hand operand or flag set.

inline Utype snt::puq::operator&(Utype lhs, Utype rhs)

Intersect two unit-system flags.

Parameters:

lhs – Left-hand operand or flag set.
rhs – Right-hand operand or flag set.

inline Utype snt::puq::operator^(Utype lhs, Utype rhs)

Compute the symmetric difference of two unit-system flags.

Parameters:

lhs – Left-hand operand or flag set.
rhs – Right-hand operand or flag set.

class BaseUnit

#include <base_units.h>

One base unit, including an optional prefix and exponent.

Public Functions

BaseUnit() = default

inline BaseUnit(const int &n)

Construct an unnamed unit factor with an integer exponent.

Parameters:: n – Integer exponent stored in the factor.

inline BaseUnit(const int &n, const int &d)

Construct a base unit with a rational exponent.

Parameters:

n – Exponent numerator.
d – Exponent denominator.

inline BaseUnit(const std::string &p, const std::string &u, const ExponentVariant &e)

Construct a base unit from a prefix, symbol, and exponent.

Parameters:

p – Unit prefix, such as k.
u – Unit symbol.
e – Unit exponent.

inline BaseUnit(const std::string &p, const std::string &u, const int &n, const int &d)

Construct a base unit from a prefix, symbol, and rational exponent.

Parameters:

p – Unit prefix, such as k.
u – Unit symbol.
n – Exponent numerator.
d – Exponent denominator.

std::string to_string(const UnitFormat &format = UnitFormat())

Format the object as text.

Parameters:: format – Formatting options controlling the textual representation.

Public Members

std::string prefix: Unit prefix, such as k or m.

std::string unit: Unit symbol.

ExponentVariant exponent: Unit exponent.

class BaseUnits

#include <base_units.h>

Ordered collection of base units representing a unit expression.

Public Types

using ListType = std::vector<BaseUnit>

Public Functions

BaseUnits() = default

BaseUnits(const std::string &s)

Parse a unit expression into base-unit factors.

Parameters:: s – Unit expression to parse.

inline BaseUnits(const BaseUnits::ListType &bu)

Construct a collection from existing base-unit factors.

Parameters:: bu – Factors to copy.

void append(const BaseUnit &bu)

Append a unit factor, combining it with an existing matching factor.

Parameters:: bu – Unit factor to append; a resulting zero exponent removes the factor.

void append(const std::string &p, const std::string &u, ExponentVariant e)

Append a factor with an exponent variant.

Parameters:

p – Unit prefix.
u – Unit symbol.
e – Integer or rational exponent.

void append(const std::string &p, const std::string &u, int n, int d)

Append a factor with a rational exponent.

Parameters:

p – Unit prefix.
u – Unit symbol.
n – Exponent numerator.
d – Exponent denominator.

std::string to_string(const UnitFormat &format = UnitFormat()) const: Format the complete unit expression.

const BaseUnit &operator[](int index) const

Access the item at the requested key or index.

Parameters:: index – Zero-based element index.

void operator*=(const BaseUnits &bu)

Multiply by the right-hand value in place.

Parameters:: bu – Base units associated with the value.

void operator/=(const BaseUnits &bu)

Divide by the right-hand value in place.

Parameters:: bu – Base units associated with the value.

BaseUnits::ListType::const_iterator begin() const

BaseUnits::ListType::const_iterator end() const

std::size_t size() const: Return the number of unit factors.

bool has_dimensions() const: Test whether any factor carries dimensions.

Dimensions dimensions() const: Calculate the combined dimensions.

Public Members

BaseUnits::ListType baseunits: Ordered base-unit factors.

Friends

friend std::ostream &operator<<(std::ostream &os, const BaseUnits &bu)

friend BaseUnits operator*(BaseUnits bu1, const BaseUnits &bu2)

friend BaseUnits operator/(BaseUnits bu1, const BaseUnits &bu2)

class Converter

#include <converter.h>

Converts values between two compatible unit expressions.

The converter is created with source and target units. Linear, logarithmic, and temperature conversions are selected from those unit definitions. A conversion with incompatible dimensions raises ConverterException.

Public Functions

inline Converter()

Converter(const BaseUnits &bu1, const BaseUnits &bu2)

Construct a converter between two explicit unit expressions.

Parameters:

bu1 – Source units.
bu2 – Target units; must have compatible dimensions with bu1.

inline Converter(const std::string &s1, const std::string &s2)

Construct a converter by parsing source and target unit expressions.

Parameters:

s1 – Source unit expression.
s2 – Target unit expression.

Result convert(const Result &m1, const Result &m2 = 1)

Convert a result from the source units to the target units.

Parameters:

m1 – Value (and optional uncertainty) to convert.
m2 – Context value required by contextual conversion rules; defaults to one.

Returns:

Converted result with uncertainty propagated through the conversion.

Public Members

Utype utype

Dimensions dimensions1

Dimensions dimensions2

class ConverterException : public snt::puq::Exception 

#include <converter.h>

Public Functions

inline ConverterException(const BaseUnits &bu1, const BaseUnits &bu2, const std::string &file, size_t line)

inline ConverterException(const BaseUnits &bu1, const SystemType &s1, const BaseUnits &bu2, const SystemType &s2, const std::string &file, const size_t line)

inline core::ExceptionInfo prepare_info(const BaseUnits &bu1, const SystemType &s1, const BaseUnits &bu2, const SystemType &s2, const std::string &file, const size_t line)

class DimensionMapExcept : public std::exception

#include <systems.h>

Public Functions

inline DimensionMapExcept(const std::string &m)

inline const char *what() const noexcept override

struct DimensionStruct

#include <systems.h>

Public Members

double estimate

double uncertainty

BaseDimensions dimensions

struct SystemDataType

#include <systems.h>

Public Members

std::string SystemAbbrev

std::string SystemName

UnitListType UnitList

QuantityListType QuantityList

DimensionMapType DimensionMap

struct UnitPrefixStruct

#include <systems.h>

Public Members

Result result

std::string definition

std::string name

struct UnitStruct

#include <systems.h>

Public Members

Utype utype

std::string definition

std::string name

bool use_prefixes

AllowedPrefixes allowed_prefixes

class UnitSystem

#include <unit_system.h>

Manages a pointer to the central unit-system registry (current).

The pointer may reference any unit system registered in SystemMap. When a UnitSystem instance is opened, the pointer is redirected to the selected unit-system data, while the previously active registry pointer is pushed onto stack.

Multiple UnitSystem instances may be open simultaneously. In that case, they must be closed in the reverse order in which they were opened (LIFO order). Each open operation pushes a new entry onto stack, and each close operation restores the previous registry by popping the corresponding entry from the stack.

Public Functions

UnitSystem(const SystemType st = SystemType::NONE)

Constructor of the UnitSystem class

Parameters:: st – Unit system type

~UnitSystem(): Destructor of the UnitSystem class

void change(const SystemType st)

Change currently openned unit system

Parameters:: st – New unit system type

void close(): Close the currently openned unit system

const std::string to_string() const

String representation of this class

Returns:: String representation

Public Static Functions

static size_t set_custom_unit(const std::string &name, const std::string &definition)

Set a custom unit into the current unit system record

Parameters:

name – Unit name
definition – Defining unit expression

Returns:

Current stack number

Public Static Attributes

static Record current: Record of a current openned unit system.

struct Record

#include <unit_system.h>

Holds record of an openned unit system

Public Members

SystemType type

SystemDataType *data

SystemDataType *custom

constexpr int snt::puq::Config::num_basedim: Number of base dimensions.

constexpr bool snt::puq::Config::use_units_temperature: Use temperature units.

constexpr bool snt::puq::Config::use_units_logarithmic: Use logarithmic units.

constexpr bool snt::puq::Config::use_system_cgs: Use CGS systems of units.

constexpr bool snt::puq::Config::use_system_nus: Use natural systems of units.

constexpr bool snt::puq::Config::use_system_eus: Use english system of units.

constexpr bool snt::puq::Config::preprocess_system: Preprocess system prefix in quantity expressions.

constexpr bool snt::puq::Config::preprocess_symbols: Preprocess special symbols in quantity expressions.

constexpr bool snt::puq::Config::debug_unit_solver: Switch on debugging diagnostics for UnitSolver.

constexpr bool snt::puq::Config::debug_calculator: Switch on debugging diagnostics for Calculator.

constexpr bool snt::puq::Config::debug_converter: Switch on debugging diagnostics for Converter.

std::string snt::puq::lists::unit_systems(const bool json = false)

std::string snt::puq::lists::prefixes(const bool json = false, const UnitFormat &format = UnitFormat())

std::string snt::puq::lists::base_units(const bool json = false, const UnitFormat &format = UnitFormat())

std::string snt::puq::lists::derived_units(const bool json = false, const UnitFormat &format = UnitFormat())

std::string snt::puq::lists::constants(const bool json = false, const UnitFormat &format = UnitFormat())

std::string snt::puq::lists::quantities(const bool json = false, const UnitFormat &format = UnitFormat())

std::string snt::puq::lists::temperature_units(const bool json = false)

std::string snt::puq::lists::logarithmic_units(const bool json = false)

constexpr std::string_view snt::puq::Symbols::plus: Symbol plus +.

constexpr std::string_view snt::puq::Symbols::minus: Symbol minus -.

constexpr std::string_view snt::puq::Symbols::minus2: Symbol minus −

constexpr std::string_view snt::puq::Symbols::multiply: Symbol multiplication *.

constexpr std::string_view snt::puq::Symbols::multiply2: Symbol multiplication ⋅

constexpr std::string_view snt::puq::Symbols::divide: Symbol division /.

constexpr std::string_view snt::puq::Symbols::power: Symbol power ^.

constexpr std::string_view snt::puq::Symbols::exponent: Symbol exponent e.

constexpr std::string_view snt::puq::Symbols::exponent2: Symbol exponent ×10.

constexpr std::string_view snt::puq::Symbols::fraction_separator: Separator in an exponent fraction (e.g. m3:2)

constexpr std::string_view snt::puq::Symbols::system_separator: Separator of an unit system in expressions (e.g. SI_m)

constexpr std::string_view snt::puq::Symbols::quantity_start: Starting symbol of a physical quantity unit (e.g. )

constexpr std::string_view snt::puq::Symbols::quantity_end: Ending symbol of a physical quantity unit.

constexpr std::string_view snt::puq::Symbols::si_factor_start: Starting symbol of an SI conversion factor (e.g. |A|)

constexpr std::string_view snt::puq::Symbols::si_factor_end: Ending symbol of an SI conversion factor.

SystemDataType snt::puq::SystemData::SI: International system of units.

SystemDataType snt::puq::SystemData::ESU: Electrostatic CGS system of units.

SystemDataType snt::puq::SystemData::EMU: Electromagnetic CGS system of units.

SystemDataType snt::puq::SystemData::GU: Gauss CGS sytem of units.

SystemDataType snt::puq::SystemData::IU: Imperial units.

SystemDataType snt::puq::SystemData::US: United States customary system of units.

SystemDataType snt::puq::SystemData::AU: Atomic system of units.

SystemDataType snt::puq::SystemData::PU: Planck system of units.

SystemDataType snt::puq::SystemData::SRU: Units for special relativity.

SystemDataType snt::puq::SystemData::GRU: Units for general relativity.

SystemDataType snt::puq::SystemData::GEO: Geometrized units.