allpix::Units

Static class to access units. More…

#include <unit.h>

Public Types

Public Functions

Detailed Description

class allpix::Units;

Static class to access units.

See: The list of framework units defined in allpix::register_units

Units are short, unique and case-insensitive strings that indicate a particular multiplication factor from the base unit in the framework. The unit system can convert external types to the system units and vise-versa for displaying purposes. Inside the framework only the defaults unit should be used, either directly or through a direct conversion.

Public Types Documentation

using UnitType

using allpix::Units::UnitType =  long double;

Type used to store the units.

Public Functions Documentation

function Units

Units() =delete

Delete default constructor (only static access)

function add

static void add(
    std::string str,
    UnitType value
)

Add a new unit to the system.

Parameters:

• str Identifier of the unit
• value Multiplication factor from the base unit

Exceptions:

• std::invalid_argument if unit is already defined
• std::invalid_argument If the unit already exists

Note: No explicit check is done for alphabetical units

Units should consist of only alphabetical characters. Units are converted to lowercase internally. All the defined units should have unique values and it is not possible to redefine them.

function getSingle

static UnitType getSingle(
    std::string str
)

Get value of a single unit in the base units.

Parameters:

• str Name of the unit

Exceptions:

• std::invalid_argument If the requested unit does not exist

Return: Value in the base unit

All units are converted to lowercase before finding their value in the internal database.

function getSingle

template <typename T >
static T getSingle(
    T inp,
    std::string str
)

Get single input parameter in the base units.

Parameters:

• inp Value in a particular unit
• str Name of that particular unit

Return: Value in the base unit

function getSingleInverse

template <typename T >
static T getSingleInverse(
    T inp,
    std::string str
)

Get single input parameter in the inverse of the base units.

Parameters:

• inp Value in a particular unit
• str Name of that particular unit

Return: Value in the base unit

function get

static UnitType get(
    const std::string & str
)

Get value of a unit in the base units.

Parameters:

• str Name of the unit

Exceptions:

• invalid_argument If one tries to get the value of an empty unit

Return: Value in the base unit

Warning: Conversions should not be done with the result of this function. The Units::get(T, const std::string&) version should be used for that purpose instead.

Units are combined by applying the multiplication operator * and the division operator / linearly. The first unit is always multiplied, following common sense. Grouping units together within brackets or parentheses is not supported. Thus any other character then a name of a unit, * or \ should lead to an error

function get

template <typename T >
static T get(
    T inp,
    const std::string & str
)

Get input parameter in the base units.

Parameters:

• inp Value in a particular unit
• str Name of that particular unit

Return: Value in the base unit

function getInverse

template <typename T >
static T getInverse(
    T inp,
    const std::string & str
)

Get input parameter in the inverse of the base units.

Parameters:

• inp Value in a particular unit
• str Name of that particular unit

Return: Value in the base unit

function convert

static UnitType convert(
    UnitType input,
    std::string str
)

Get base unit in the requested unit.

Parameters:

• input Value in the base unit system
• str Name of the output unit

Return: Value in the requested unit

function display

static std::string display(
    UnitType input,
    std::initializer_list< std::string > units
)

Return value for display in the best of all the provided units.

Parameters:

• input Value in the base unit system
• units Name of the possible output units

Exceptions:

• std::invalid_argument If the list of units is empty

Return: Value with best unit to be used for display

The best unit is determined using the rules below:

• If the input is zero, the best unit can’t be determined and the first one will be used.
• If there exists at least one unit for which the value is larger than one, the unit with value nearest to one is chosen from all units with values larger than one
• Otherwise the unit is chosen that has a value as close as possible to one (from below)

function display

static std::string display(
    UnitType input,
    std::string unit
)

Return value in the requested unit for display.

Parameters:

• input Value in other type
• unit Name of the output unit

Return: Value with unit to be used for display

function display

template <typename T >
static std::string display(
    T input,
    std::initializer_list< std::string > units
)

Return value for display in the best of all the provided units for all vector elements.

Parameters:

• input Vector of values in the base unit system
• units Name of the possible output units

Return: Vector of values between parentheses with best display units for each element

Note: Works for all vector types that can be converted to a string using the stringutilities".

Updated on 2025-02-27 at 14:14:46 +0000