Files
mp-units/src/core/include/units/unit.h
T

479 lines
17 KiB
C++
Raw Normal View History

// The MIT License (MIT)
//
// Copyright (c) 2018 Mateusz Pusz
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
#pragma once
#include <units/bits/expression_template.h>
#include <units/bits/external/fixed_string.h>
#include <units/bits/external/type_name.h>
2022-08-01 11:59:00 +02:00
#include <units/bits/external/type_traits.h>
#include <units/magnitude.h>
#include <units/symbol_text.h>
// #include <units/bits/derived_symbol_text.h>
2021-03-30 13:21:05 +02:00
// IWYU pragma: begin_exports
// #include <units/bits/absolute_magnitude.h>
// #include <units/ratio.h>
2021-03-30 13:21:05 +02:00
// IWYU pragma: end_exports
namespace units {
namespace detail {
2019-12-09 17:19:58 +01:00
2022-10-06 23:43:01 +01:00
template<typename T>
2022-10-18 21:24:09 +02:00
inline constexpr bool is_unit = false;
2022-10-06 23:43:01 +01:00
2022-10-20 14:03:15 +02:00
} // namespace detail
/**
* @brief A concept matching all unit types in the library
*
2022-10-20 14:03:15 +02:00
* Satisfied by all unit types provided by the library.
*/
template<typename T>
2022-10-18 21:24:09 +02:00
concept Unit = detail::is_unit<T>;
2022-10-20 14:03:15 +02:00
/**
* @brief Unit being a scaled version of another unit
*
* @tparam M magnitude describing the scale factor
* @tparam U reference unit being scaled
*
* @note User should not instantiate this type! It is not exported from the C++ module. The library will
* instantiate this type automatically based on the unit arithmetic equation provided by the user.
*/
2022-10-18 21:24:09 +02:00
template<Magnitude auto M, Unit U>
2022-10-20 14:03:15 +02:00
struct scaled_unit {
static constexpr UNITS_MSVC_WORKAROUND(Magnitude) auto mag = M;
static constexpr U reference_unit{};
};
namespace detail {
template<typename T>
inline constexpr bool is_specialization_of_scaled_unit = false;
template<auto M, Unit U>
inline constexpr bool is_specialization_of_scaled_unit<scaled_unit<M, U>> = true;
} // namespace detail
2019-04-11 13:36:06 +01:00
2019-12-01 19:47:58 +01:00
/**
* @brief A named unit
*
2022-10-20 14:03:15 +02:00
* Defines a unit with a special name.
* Most of the named units may be composed with a prefix to create a `prefixed_unit`.
*
* For example:
*
* @code{.cpp}
* inline constexpr struct second : named_unit<"s"> {} second;
* inline constexpr struct metre : named_unit<"m"> {} metre;
* inline constexpr struct hertz : named_unit<"Hz", 1 / second> {} hertz;
* inline constexpr struct newton : named_unit<"N", kilogram * metre / square<second>> {} newton;
* inline constexpr struct degree_Celsius : named_unit<basic_symbol_text{"\u00B0C", "`C"}, kelvin> {} degree_Celsius;
* inline constexpr struct minute : named_unit<"min", mag<60> * second> {} minute;
* @endcode
*
* @note A common convention in this library is to assign the same name for a type and an object of this type.
* Besides defining them user never works with the unit types in the source code. All operations
* are done on the objects. Contrarily, the unit types are the only one visible in the compilation
* errors. Having them of the same names improves user experience and somehow blurs those separate domains.
2019-12-01 19:47:58 +01:00
*
* @tparam Symbol a short text representation of the unit
*/
template<basic_symbol_text Symbol, auto...>
struct named_unit;
2022-10-20 14:03:15 +02:00
/**
* @brief Specialization for base unit
*
* Defines a base unit in the system of units (i.e. `metre`).
* or a name assigned to another scaled or derived unit (i.e. `hour`, `joule`).
* Most of the named units may be composed with a prefix to create a `prefixed_unit`.
*
* @tparam Symbol a short text representation of the unit
*/
template<basic_symbol_text Symbol>
requires(!Symbol.empty())
2022-10-18 21:24:09 +02:00
struct named_unit<Symbol> {
2022-10-20 14:03:15 +02:00
static constexpr auto symbol = Symbol; ///< Unique base unit identifier
2019-12-01 19:47:58 +01:00
};
2019-04-11 13:36:06 +01:00
2022-10-20 14:03:15 +02:00
/**
* @brief Specialization for a unit with special name
*
* Allows assigning a special name to another scaled or derived unit (i.e. `hour`, `joule`).
*
* @tparam Symbol a short text representation of the unit
* @tparam Unit a unit for which we provide a special name
*/
2022-10-06 23:43:01 +01:00
template<basic_symbol_text Symbol, Unit auto U>
requires(!Symbol.empty())
struct named_unit<Symbol, U> : std::remove_const_t<decltype(U)> {
2022-10-20 14:03:15 +02:00
static constexpr auto symbol = Symbol; ///< Unique unit identifier
2019-12-01 19:47:58 +01:00
};
2019-04-11 13:36:06 +01:00
2022-10-18 21:24:09 +02:00
namespace detail {
template<basic_symbol_text Symbol, auto... Args>
void to_base_specialization_of_named_unit(const volatile named_unit<Symbol, Args...>*);
2022-10-20 14:03:15 +02:00
template<typename T>
inline constexpr bool is_specialization_of_named_unit = false;
template<basic_symbol_text Symbol, auto... Args>
inline constexpr bool is_specialization_of_named_unit<named_unit<Symbol, Args...>> = true;
2022-10-18 21:24:09 +02:00
} // namespace detail
2022-10-20 14:03:15 +02:00
/**
* @brief A concept matching all units with special names
*
* Satisfied by all unit types derived from the specialization of `named_unit`.
*/
2022-10-18 21:24:09 +02:00
template<typename T>
2022-10-20 14:03:15 +02:00
concept NamedUnit = Unit<T> && requires(T* t) { detail::to_base_specialization_of_named_unit(t); } &&
(!detail::is_specialization_of_named_unit<T>);
2022-10-18 21:24:09 +02:00
2022-10-20 14:03:15 +02:00
/**
* @brief Prevents assignment of a prefix to specific units
*
* By default all named units allow assigning a prefix for them. There are some notable exceptions like
* `hour` or `degree_Celsius`. For those a partial specialization with the value `false` should be
* provided.
*/
template<NamedUnit auto V>
inline constexpr bool unit_can_be_prefixed = true;
2022-10-18 21:24:09 +02:00
2022-10-20 14:03:15 +02:00
/**
* @brief A concept to be used to define prefixes for a unit
*/
2022-10-19 13:15:02 +02:00
template<typename T>
concept PrefixableUnit = NamedUnit<T> && unit_can_be_prefixed<T{}>;
2022-10-20 14:03:15 +02:00
2019-12-01 19:47:58 +01:00
/**
* @brief A prefixed unit
*
2022-10-20 14:03:15 +02:00
* Defines a new unit that is a scaled version of another unit with the scaling
* factor specified by a predefined prefix.
2019-12-01 19:47:58 +01:00
*
2022-10-20 14:03:15 +02:00
* For example:
*
* @code{.cpp}
* template<PrefixableUnit auto U>
* struct kilo_ : prefixed_unit<"k", mag_power<10, 3>, U> {};
*
* template<PrefixableUnit auto U>
* inline constexpr kilo_<U> kilo;
*
* inline constexpr struct kilogram : decltype(si::kilo<gram>) {} kilogram;
* @endcode
*
* @tparam Symbol a prefix text to prepend to a unit symbol
* @tparam M scaling factor of the prefix
* @tparam U a named unit to be prefixed
2019-12-01 19:47:58 +01:00
*/
2022-10-19 13:15:02 +02:00
template<basic_symbol_text Symbol, Magnitude auto M, PrefixableUnit auto U>
requires(!Symbol.empty())
2022-10-18 21:24:09 +02:00
struct prefixed_unit : std::remove_const_t<decltype(M * U)> {
static constexpr auto symbol = Symbol + U.symbol;
2022-10-06 23:43:01 +01:00
};
namespace detail {
2022-10-18 21:24:09 +02:00
template<typename T>
inline constexpr bool is_power_of_unit =
requires { requires is_specialization_of_power<T> && Unit<typename T::factor>; };
2022-10-18 21:24:09 +02:00
template<typename T>
concept UnitLike = Unit<T> || is_power_of_unit<T>;
2022-10-18 21:24:09 +02:00
template<typename T>
inline constexpr bool is_per_of_units = false;
2022-10-18 21:24:09 +02:00
template<typename... Ts>
inline constexpr bool is_per_of_units<per<Ts...>> = (... && UnitLike<Ts>);
} // namespace detail
2022-10-18 21:24:09 +02:00
template<typename T>
2022-10-20 14:03:15 +02:00
concept DerivedUnitSpec = detail::UnitLike<T> || detail::is_per_of_units<T>;
2022-10-18 21:24:09 +02:00
2022-10-20 14:03:15 +02:00
/**
* @brief Measurement unit for a derived quantity
*
* Derived units are defined as products of powers of the base units.
*
* Instead of using a raw list of exponents this library decided to use expression template syntax to make types
* more digestable for the user. The positive exponents are ordered first and all negative exponents are put as a list
* into the `per<...>` class template. If a power of exponent is different than `1` the unit type is enclosed in
* `power<Dim, Num, Den>` class template. Otherwise, it is just put directly in the list without any wrapper. There
* is also one special case. In case all of the exponents are negative then the `one` being a coherent unit of
* a dimensionless quantity is put in the front to increase the readability.
*
* For example:
*
* @code{.cpp}
* static_assert(is_of_type<1 / second, derived_unit<one, per<second>>>);
* static_assert(is_of_type<1 / (1 / second), second>);
* static_assert(is_of_type<one * second, second>);
* static_assert(is_of_type<metre * metre, derived_unit<power<metre, 2>>>);
* static_assert(is_of_type<metre * second, derived_unit<metre, second>>);
* static_assert(is_of_type<metre / second, derived_unit<metre, per<second>>>);
* static_assert(is_of_type<metre / square<second>, derived_unit<metre, per<power<second, 2>>>>);
* static_assert(is_of_type<watt / joule, derived_unit<watt, per<joule>>>);
* @endcode
*
* Every unit in the library has its internal canonical representation being the list of exponents of named base units
* (with the exception of `kilogram` which is represented as `gram` here) and a scaling ratio represented with a
* magnitude.
*
* Two units are deemed convertible if their canonical version has units of the same type.
* Two units are equivalent when they are convertible and their canonical versions have the same scaling ratios.
*
* The above means that:
* - `1/s` and `Hz` are both convertible and equal
* - `m` and `km` are convertible but not equal
* - `m` and `m²` ane not convertible and not equal
*
* @note This also means that units like `hertz` and `becquerel` are also considered convertible and equal.
*
* @tparam Us a parameter pack consisting tokens allowed in the unit specification
* (units, `power<U, Num, Den>`, `per<...>`)
*
* @note User should not instantiate this type! It is not exported from the C++ module. The library will
* instantiate this type automatically based on the unit arithmetic equation provided by the user.
*/
template<DerivedUnitSpec... Us>
2022-10-18 21:24:09 +02:00
struct derived_unit : detail::expr_fractions<derived_unit<>, Us...> {};
/**
* @brief Unit one
*
* Unit of a dimensionless quantity.
*/
inline constexpr struct one : derived_unit<> {
} one;
namespace detail {
template<auto M, typename U>
void is_unit_impl(const volatile scaled_unit<M, U>*);
template<basic_symbol_text Symbol, auto... Args>
void is_unit_impl(const volatile named_unit<Symbol, Args...>*);
template<typename... Us>
void is_unit_impl(const volatile derived_unit<Us...>*);
template<typename T>
requires requires(T* t) { is_unit_impl(t); }
inline constexpr bool is_unit<T> = true;
/**
2022-10-20 14:03:15 +02:00
* @brief A canonical representation of a unit
2022-10-18 21:24:09 +02:00
*
2022-10-20 14:03:15 +02:00
* A canonical representation of a unit consists of a `reference_unit` and its scaling
* factor represented by the magnitude `mag`.
2022-10-18 21:24:09 +02:00
*
2022-10-20 14:03:15 +02:00
* `reference_unit` is a unit (possibly derived one) that consists only named base units.
* All of the intermediate derived units are extracted, prefixes and magnitudes of scaled
* units are stripped from them and accounted in the `mag`.
2022-10-18 21:24:09 +02:00
*
2022-10-20 14:03:15 +02:00
* All units having the same canonical unit are deemed equal.
* All units having the same `reference_unit` are convertible (their `mag` may differ
* and is the subject of conversion).
2022-10-18 21:24:09 +02:00
*
2022-10-20 14:03:15 +02:00
* @tparam U a unit to use as a `reference_unit`
* @tparam M a Magnitude representing an absolute scaling factor of this unit
2022-10-18 21:24:09 +02:00
*/
2022-10-20 14:03:15 +02:00
template<Magnitude M, UnitLike U>
2022-10-18 21:24:09 +02:00
struct canonical_unit {
M mag;
2022-10-20 14:03:15 +02:00
U reference_unit;
2022-10-18 21:24:09 +02:00
};
[[nodiscard]] constexpr auto get_canonical_unit(UnitLike auto u);
template<UnitLike T, auto M, typename U>
[[nodiscard]] constexpr auto get_canonical_unit_impl(T, const volatile scaled_unit<M, U>&)
{
auto base = get_canonical_unit(U{});
2022-10-20 14:03:15 +02:00
return canonical_unit{M * base.mag, base.reference_unit};
2022-10-18 21:24:09 +02:00
}
template<UnitLike T, basic_symbol_text Symbol>
[[nodiscard]] constexpr auto get_canonical_unit_impl(T t, const volatile named_unit<Symbol>&)
{
2022-10-20 14:03:15 +02:00
return canonical_unit{mag<1>, t};
2022-10-18 21:24:09 +02:00
}
template<UnitLike T, basic_symbol_text Symbol, Unit auto U>
[[nodiscard]] constexpr auto get_canonical_unit_impl(T, const volatile named_unit<Symbol, U>&)
{
return get_canonical_unit(U);
}
template<UnitLike T, typename F, int Num, int... Den>
[[nodiscard]] constexpr auto get_canonical_unit_impl(T, const volatile power<F, Num, Den...>&)
{
auto base = get_canonical_unit(F{});
return canonical_unit{
2022-10-20 14:03:15 +02:00
pow<power<F, Num, Den...>::exponent>(base.mag),
derived_unit<power_or_T<std::remove_const_t<decltype(base.reference_unit)>, power<F, Num, Den...>::exponent>>{}};
2022-10-18 21:24:09 +02:00
}
2022-10-20 14:03:15 +02:00
template<UnitLike T, DerivedUnitSpec... Us>
2022-10-18 21:24:09 +02:00
[[nodiscard]] constexpr auto get_canonical_unit_impl(T, const volatile derived_unit<Us...>&)
{
if constexpr (type_list_size<typename derived_unit<Us...>::_den_> != 0) {
auto num = get_canonical_unit(type_list_map<typename derived_unit<Us...>::_num_, derived_unit>{});
auto den = get_canonical_unit(type_list_map<typename derived_unit<Us...>::_den_, derived_unit>{});
2022-10-20 14:03:15 +02:00
return canonical_unit{num.mag / den.mag, num.reference_unit / den.reference_unit};
2022-10-18 21:24:09 +02:00
} else {
auto num = (one * ... * get_canonical_unit(Us{}).reference_unit);
auto mag = (units::mag<1> * ... * get_canonical_unit(Us{}).mag);
2022-10-20 14:03:15 +02:00
return canonical_unit{mag, num};
2022-10-18 21:24:09 +02:00
}
}
[[nodiscard]] constexpr auto get_canonical_unit(UnitLike auto u) { return get_canonical_unit_impl(u, u); }
2022-10-20 14:03:15 +02:00
// TODO What if the same unit will have different types (i.e. user will inherit its own type from `metre`)?
// Is there a better way to sort units here? Some of them may not have symbol at all (like all units of
// dimensionless quantities).
2022-10-18 21:24:09 +02:00
template<Unit U1, Unit U2>
struct unit_less : std::bool_constant<type_name<U1>() < type_name<U2>()> {};
template<typename T1, typename T2>
using type_list_of_unit_less = expr_less<T1, T2, unit_less>;
} // namespace detail
// Operators
2022-10-20 14:03:15 +02:00
/**
* Multiplication by `1` returns the same unit, otherwise `scaled_unit` is being returned.
*/
2022-10-06 23:43:01 +01:00
template<Magnitude M, Unit U>
2022-10-20 14:03:15 +02:00
[[nodiscard]] consteval Unit auto operator*(M mag, U u)
2022-10-06 23:43:01 +01:00
{
2022-10-20 14:03:15 +02:00
if constexpr (mag == units::mag<1>)
return u;
else
return scaled_unit<mag, std::remove_const_t<U>>{};
2022-10-06 23:43:01 +01:00
}
2022-10-18 21:24:09 +02:00
template<Magnitude M, Unit U>
[[nodiscard]] consteval Unit auto operator*(U, M) = delete;
2022-10-06 23:43:01 +01:00
2022-10-20 14:03:15 +02:00
/**
* `scaled_unit` specializations have priority in this operation. This means that the library framework
* prevents passing it as an element to the `derived_unit`. In such case only the reference unit is passed
* to the derived unit and the magnitude remains outside forming another scaled unit as a result of the operation.
*/
template<Unit U1, Unit U2>
2022-10-20 14:03:15 +02:00
[[nodiscard]] consteval Unit auto operator*(U1 u1, U2 u2)
{
2022-10-20 14:03:15 +02:00
if constexpr (detail::is_specialization_of_scaled_unit<U1> && detail::is_specialization_of_scaled_unit<U2>)
return (U1::mag * U2::mag) * (U1::reference_unit * U2::reference_unit);
else if constexpr (detail::is_specialization_of_scaled_unit<U1>)
return U1::mag * (U1::reference_unit * u2);
else if constexpr (detail::is_specialization_of_scaled_unit<U2>)
return U2::mag * (u1 * U2::reference_unit);
else
return detail::expr_multiply<U1, U2, struct one, detail::type_list_of_unit_less, derived_unit>();
}
2022-10-20 14:03:15 +02:00
/**
* `scaled_unit` specializations have priority in this operation. This means that the library framework
* prevents passing it as an element to the `derived_unit`. In such case only the reference unit is passed
* to the derived unit and the magnitude remains outside forming another scaled unit as a result of the operation.
*/
template<Unit U1, Unit U2>
2022-10-20 14:03:15 +02:00
[[nodiscard]] consteval Unit auto operator/(U1 u1, U2 u2)
{
2022-10-20 14:03:15 +02:00
if constexpr (detail::is_specialization_of_scaled_unit<U1> && detail::is_specialization_of_scaled_unit<U2>)
return (U1::mag / U2::mag) * (U1::reference_unit / U2::reference_unit);
else if constexpr (detail::is_specialization_of_scaled_unit<U1>)
return U1::mag * (U1::reference_unit / u2);
else if constexpr (detail::is_specialization_of_scaled_unit<U2>)
return U2::mag * (u1 / U2::reference_unit);
else
return detail::expr_divide<U1, U2, struct one, detail::type_list_of_unit_less, derived_unit>();
}
template<Unit U>
2022-09-15 14:52:54 -06:00
[[nodiscard]] consteval Unit auto operator/(int value, U)
{
gsl_Assert(value == 1);
return detail::expr_invert<U, struct one, derived_unit>();
}
2022-10-18 21:24:09 +02:00
template<Unit U>
[[nodiscard]] consteval Unit auto operator/(U, int) = delete;
template<Unit U1, Unit U2>
2022-10-18 21:24:09 +02:00
[[nodiscard]] consteval bool operator==(U1 lhs, U2 rhs)
{
2022-10-18 21:24:09 +02:00
auto canonical_lhs = detail::get_canonical_unit(lhs);
auto canonical_rhs = detail::get_canonical_unit(rhs);
return is_same_v<decltype(canonical_lhs.reference_unit), decltype(canonical_rhs.reference_unit)> &&
canonical_lhs.mag == canonical_rhs.mag;
}
2022-10-06 23:43:01 +01:00
2022-10-18 21:24:09 +02:00
// Convertible
2022-10-09 21:32:38 +01:00
template<Unit U1, Unit U2>
2022-10-18 21:24:09 +02:00
[[nodiscard]] consteval bool convertible(U1 lhs, U2 rhs)
2022-10-09 21:32:38 +01:00
{
2022-10-18 21:24:09 +02:00
auto canonical_lhs = detail::get_canonical_unit(lhs);
auto canonical_rhs = detail::get_canonical_unit(rhs);
return is_same_v<decltype(canonical_lhs.reference_unit), decltype(canonical_rhs.reference_unit)>;
2022-10-09 21:32:38 +01:00
}
2022-10-20 14:03:15 +02:00
// Helper variable templates to create common powers
2022-10-18 21:24:09 +02:00
template<Unit auto U>
2022-10-20 14:03:15 +02:00
inline constexpr decltype(U * U) square;
2022-10-18 21:24:09 +02:00
2022-10-06 23:43:01 +01:00
template<Unit auto U>
2022-10-20 14:03:15 +02:00
inline constexpr decltype(U * U * U) cubic;
2022-10-06 23:43:01 +01:00
} // namespace units
2022-10-09 21:32:38 +01:00
namespace std {
// TODO implement this
template<units::Unit U1, units::Unit U2>
requires(units::convertible(U1{}, U2{}))
struct common_type<U1, U2> {
using type = ::units::conditional<std::derived_from<std::remove_const_t<U1>, std::remove_const_t<U2>>,
std::remove_const_t<U1>, std::remove_const_t<U2>>;
};
} // namespace std