diff --git a/docs/getting_started/quick_start.md b/docs/getting_started/quick_start.md index 4a76744f..0c833fa8 100644 --- a/docs/getting_started/quick_start.md +++ b/docs/getting_started/quick_start.md @@ -238,7 +238,7 @@ This introduces an additional type-safety. using namespace mp_units::si::unit_symbols; using namespace mp_units::usc::unit_symbols; - quantity_point temp{20. * deg_C}; + quantity_point temp = 20. * absolute(deg_C); std::println("Temperature: {} ({})", temp.quantity_from_zero(), temp.in(deg_F).quantity_from_zero()); @@ -259,7 +259,7 @@ This introduces an additional type-safety. using namespace mp_units::si::unit_symbols; using namespace mp_units::usc::unit_symbols; - quantity_point temp{20. * deg_C}; + quantity_point temp = 20. * absolute(deg_C); std::println("Temperature: {} ({})", temp.quantity_from_zero(), temp.in(deg_F).quantity_from_zero()); diff --git a/docs/users_guide/framework_basics/design_overview.md b/docs/users_guide/framework_basics/design_overview.md index 04857726..72ac7a71 100644 --- a/docs/users_guide/framework_basics/design_overview.md +++ b/docs/users_guide/framework_basics/design_overview.md @@ -378,5 +378,5 @@ For example: the previous example: ```cpp - constexpr auto room_reference_temperature = ice_point + isq::Celsius_temperature(21 * deg_C); + constexpr auto room_reference_temperature = ice_point + isq::Celsius_temperature(21 * delta(deg_C)); ``` diff --git a/docs/users_guide/framework_basics/the_affine_space.md b/docs/users_guide/framework_basics/the_affine_space.md index 54fe7cf2..ffba731f 100644 --- a/docs/users_guide/framework_basics/the_affine_space.md +++ b/docs/users_guide/framework_basics/the_affine_space.md @@ -3,7 +3,7 @@ The affine space has two types of entities: - **_Point_** - a position specified with coordinate values (e.g., location, address, etc.) -- **_Displacement vectors_** - the difference between two points (e.g., shift, offset, +- **_Displacement vector_** - the difference between two points (e.g., shift, offset, displacement, duration, etc.) In the following subchapters, we will often refer to _displacement vectors_ simply as _vectors_ for @@ -70,6 +70,49 @@ difference between two things: As we already know, a `quantity` type provides all operations required for a _displacement vector_ abstraction in an affine space. +Quantities are constructed from a delta quantity reference. Most of units are considered to be +delta references by default. The ones that need a special qualification are the units that +get a point origin in their definition (i.e., units of temperature). + +We can create a `quantity` by passing a delta quantity reference to either: + +- two-parameter constructor: + + ```cpp + quantity q1(42, si::metre); + // quantity q2(42, si::kelvin); // Compile-time error + // quantity q3(42, si::degree_Celsius); // Compile-time error + // quantity q4(42, usc::degree_Fahrenheit); // Compile-time error + quantity q5(42, delta(si::metre)); + quantity q6(42, delta(si::kelvin)); + quantity q7(42, delta(si::degree_Celsius)); + quantity q8(42, delta(usc::degree_Fahrenheit)); + ``` + +- multiply syntax: + + ```cpp + quantity q1 = 42 * m; + // quantity q2 = 42 * K; // Compile-time error + // quantity q3 = 42 * deg_C; // Compile-time error + // quantity q4 = 42 * deg_F; // Compile-time error + quantity q5 = 42 * delta(m); + quantity q6 = 42 * delta(K); + quantity q7 = 42 * delta(deg_C); + quantity q8 = 42 * delta(deg_F); + ``` + +!!! note + + `delta` specifier is used to qualify the entire reference upon `quantity` construction. + It does not satisfy the [`Reference`](concepts.md#Reference) concept. This means that, + for example, the below are ill-formed: + + ```cpp + void foo(quantity temp); // ill-formed + quantity specific_heat_capacity; // ill-formed + quantity R = 8.314 * N * m / (delta(deg_C) * mol); // ill-formed + ``` ## _Point_ is modeled by `quantity_point` and `PointOrigin` @@ -109,6 +152,19 @@ scale zeroth point using the following rules: - otherwise, an instantiation of `zeroth_point_origin` is being used which provides a well-established zeroth point for a specific quantity type. +Quantity points with default point origins may be constructed using multiply syntax from an +absolute quantity reference. None of units are considered to be absolute references by default, +so they need a special qualification: + +```cpp +// quantity_point qp1 = 42 * m; // Compile-time error +// quantity_point qp2 = 42 * K; // Compile-time error +// quantity_point qp3 = 42 * deg_C; // Compile-time error +quantity_point qp4 = 42 * absolute(m); +quantity_point qp5 = 42 * absolute(K); +quantity_point qp6 = 42 * absolute(deg_C); +``` + !!! tip The `quantity_point` definition can be found in the `mp-units/quantity_point.h` header file. @@ -124,8 +180,8 @@ for this domain. ![affine_space_1](affine_space_1.svg){style="width:80%;display: block;margin: 0 auto;"} ```cpp -quantity_point qp1{100 * m}; -quantity_point qp2{120 * m}; +quantity_point qp1 = 100 * absolute(m); +quantity_point qp2 = 120 * absolute(m); assert(qp1.quantity_from_zero() == 100 * m); assert(qp2.quantity_from_zero() == 120 * m); @@ -174,8 +230,8 @@ origin. ```cpp inline constexpr struct origin final : absolute_point_origin {} origin; -// quantity_point qp1{100 * m}; // Compile-time error -// quantity_point qp2{120 * m}; // Compile-time error +// quantity_point qp1{100 * m}; // Compile-time error +// quantity_point qp2 = 120 * absolute(m); // Compile-time error quantity_point qp1 = origin + 100 * m; quantity_point qp2 = 120 * m + origin; @@ -387,7 +443,7 @@ namespace si { inline constexpr struct absolute_zero final : absolute_point_origin {} absolute_zero; inline constexpr auto zeroth_kelvin = absolute_zero; -inline constexpr struct ice_point final : relative_point_origin}> {} ice_point; +inline constexpr struct ice_point final : relative_point_origin<273'150 * absolute(milli)}> {} ice_point; inline constexpr auto zeroth_degree_Celsius = ice_point; } @@ -395,7 +451,7 @@ inline constexpr auto zeroth_degree_Celsius = ice_point; namespace usc { inline constexpr struct zeroth_degree_Fahrenheit final : - relative_point_origin * si::degree_Celsius)}> {} zeroth_degree_Fahrenheit; + relative_point_origin<-32 * absolute(mag_ratio<5, 9> * si::degree_Celsius)> {} zeroth_degree_Fahrenheit; } ``` @@ -444,25 +500,28 @@ choose from here. Depending on our needs or tastes, we can: - be explicit about the unit and origin: ```cpp - quantity_point q1 = si::zeroth_degree_Celsius + 20.5 * deg_C; - quantity_point q2 = {20.5 * deg_C, si::zeroth_degree_Celsius}; - quantity_point q3{20.5 * deg_C}; + quantity_point q1 = si::zeroth_degree_Celsius + 20.5 * delta(deg_C); + quantity_point q2 = {20.5 * delta(deg_C), si::zeroth_degree_Celsius}; + quantity_point q3{20.5 * delta(deg_C)}; + quantity_point q4 = 20.5 * absolute(deg_C); ``` - specify a unit and use its zeroth point origin implicitly: ```cpp - quantity_point q4 = si::zeroth_degree_Celsius + 20.5 * deg_C; - quantity_point q5 = {20.5 * deg_C, si::zeroth_degree_Celsius}; - quantity_point q6{20.5 * deg_C}; + quantity_point q5 = si::zeroth_degree_Celsius + 20.5 * delta(deg_C); + quantity_point q6 = {20.5 * delta(deg_C), si::zeroth_degree_Celsius}; + quantity_point q7{20.5 * delta(deg_C)}; + quantity_point q8 = 20.5 * absolute(deg_C); ``` - benefit from CTAD: ```cpp - quantity_point q7 = si::zeroth_degree_Celsius + 20.5 * deg_C; - quantity_point q8 = {20.5 * deg_C, si::zeroth_degree_Celsius}; - quantity_point q9{20.5 * deg_C}; + quantity_point q9 = si::zeroth_degree_Celsius + 20.5 * delta(deg_C); + quantity_point q10 = {20.5 * delta(deg_C), si::zeroth_degree_Celsius}; + quantity_point q11{20.5 * delta(deg_C)}; + quantity_point q12 = 20.5 * absolute(deg_C); ``` In all of the above cases, we end up with the `quantity_point` of the same type and value. @@ -473,10 +532,10 @@ the following way: ![affine_space_6](affine_space_6.svg){style="width:80%;display: block;margin: 0 auto;"} ```cpp -constexpr struct room_reference_temp final : relative_point_origin {} room_reference_temp; +constexpr struct room_reference_temp final : relative_point_origin<21 * absolute(deg_C)> {} room_reference_temp; using room_temp = quantity_point; -constexpr auto step_delta = isq::Celsius_temperature(0.5 * deg_C); +constexpr auto step_delta = isq::Celsius_temperature(0.5 * delta(deg_C)); constexpr int number_of_steps = 6; room_temp room_ref{};