Support Quantity non-type template parameters (#318)

Technically, we can't get non-type template parameters of custom class
type until C++20.  But for a `Quantity<U, R>` whose rep `R` is integral,
we can get the next best thing!

This PR introduces a public member typedef, `Quantity<U, R>::NTTP`,
which _can_ be used as a template parameter, because it's an
enumeration.  We support _bidirectional, implicit_ conversion between
`Quantity<U, R>` and `Quantity<U, R>::NTTP`, as long as there's an exact
match for `U` and `R`.  In all other cases, users must use the usual
`Quantity` conversion operators to get it into the right type.  They can
also explicitly request conversion from the NTTP to the `Quantity` by
passing the former to `from_nttp(...)`.

It's a niche use case, but it's finally possible to use a `Quantity` as
a template parameter in a unit-safe way!  There just was no other
comparable solution before this.

Compile time measurements are ongoing, but so far they suggest a small
but nonzero penalty.  It appears that it varies from file to file, but
is generally less than 50 ms.  I think that's an OK price to pay for
this feature.

Fixes #316.

au/code/au/quantity.hh

@@ -385,6 +385,34 @@ class Quantity {
             CorrespondingQuantityT<T>{*this}.in(typename CorrespondingQuantity<T>::Unit{}));
     }
 
+    ////////////////////////////////////////////////////////////////////////////////////////////////
+    // Pre-C++20 Non-Type Template Parameter (NTTP) functionality.
+    //
+    // If `Rep` is a built in integral type, then `Quantity::NTTP` can be used as a template
+    // parameter.
+
+    enum class NTTP : std::conditional_t<std::is_integral<Rep>::value, Rep, bool> {
+        ENUM_VALUES_ARE_UNUSED
+    };
+
+    constexpr Quantity(NTTP val) : value_{static_cast<Rep>(val)} {
+        static_assert(std::is_integral<Rep>::value,
+                      "NTTP functionality only works when rep is built-in integral type");
+    }
+
+    constexpr operator NTTP() const {
+        static_assert(std::is_integral<Rep>::value,
+                      "NTTP functionality only works when rep is built-in integral type");
+        return static_cast<NTTP>(value_);
+    }
+
+    template <typename C, C x = C::ENUM_VALUES_ARE_UNUSED>
+    constexpr operator C() const = delete;
+    // If you got here ^^^, then you need to do your unit conversion **manually**.  Check the type
+    // of the template parameter, and convert it to that same unit and rep.
+
+    friend constexpr Quantity from_nttp(NTTP val) { return val; }
+
  private:
     template <typename OtherUnit, typename OtherRep>
     static constexpr void warn_if_integer_division() {

au/code/au/quantity_test.cc

@@ -748,6 +748,22 @@ TEST(Quantity, CommonUnitAlwaysCompletelyIndependentOfOrder) {
     check_units(kilo(meters), miles, milli(meters));
 }
 
+template <QuantityI<Meters>::NTTP Length>
+struct TemplateOnLength {
+    QuantityI<Meters> value = Length;
+};
+
+TEST(QuantityNTTP, SupportsPreCpp20NttpTypes) {
+    constexpr auto length = TemplateOnLength<meters(18)>{}.value;
+    EXPECT_THAT(length, SameTypeAndValue(meters(18)));
+}
+
+TEST(QuantityNTTP, CanConvertFromNttpToAnyCompatibleQuantityType) {
+    constexpr QuantityI<Meters>::NTTP LengthNTTP = meters(18);
+    constexpr QuantityI<Milli<Meters>> length = from_nttp(LengthNTTP);
+    EXPECT_THAT(length, SameTypeAndValue(milli(meters)(18'000)));
+}
+
 TEST(Quantity, CommonTypeRespectsImplicitRepSafetyChecks) {
     // The following test should fail to compile.  Uncomment both lines to check.
     // constexpr auto feeters = QuantityMaker<CommonUnitT<Meters, Feet>>{};

docs/reference/quantity.md

@@ -377,6 +377,50 @@ These functions also support an explicit template parameter: so, `.coerce_as<T>(
     Prefer **not** to use the "coercing versions" if possible, because you will get more safety
     checks.  The risks which the "base" versions warn about are real.
 
+## Non-Type Template Parameters (NTTPs) {#nttp}
+
+A _non-type template parameter_ (NTTP) is a template parameter that is not a _type_, but rather some
+kind of _value_.  Common examples include `template<int N>`, or `template<bool B>`.  Before C++20,
+only a small number of types could be used as NTTPs: very roughly, these were _integral_ types,
+_pointer_ types, and _enumerations_.
+
+Au provides a workaround for pre-C++20 users that lets you _effectively_ encode any `Quantity<U, R>`
+as an NTTP, _as long as_ its rep `R` is an **integral** type.  To do this, use the
+`Quantity<U, R>::NTTP` type as the template parameter.  You will be able to assign between
+`Quantity<U, R>` and `Quantity<U, R>::NTTP`, _in either direction_, but only in the case of exact
+match of both `U` and `R`.  For all other cases, you'll need to perform a conversion (using the
+usual mechanisms for `Quantity` described elsewhere on this page).
+
+!!! warning
+    It is undefined behavior to invoke `Quantity<U, R>::NTTP` whenever `std::is_integral<R>::value`
+    is `false`.
+
+    We cannot strictly prevent users from doing this.  However, in practice, it is very unlikely for
+    this to happen by accident.  Both conversion operators between `Quantity<U, R>` and
+    `Quantity<U, R>::NTTP` would fail with a hard compiler error, based on a `static_assert` that
+    explains this situation.  So users can name this type, but they cannot assign to it or from it
+    without prohibitive difficulty.
+
+??? example "Example: defining and using a template with a `Quantity` NTTP"
+    ```cpp
+    template <QuantityI<Hertz>::NTTP Frequency>
+    struct TemplatedOnFrequency {
+        QuantityI<Hertz> value = Frequency;      // Assigning `Quantity` from NTTP
+    };
+
+    using T = TemplatedOnFrequency<hertz(440)>;  // Setting template parameter from `Quantity`
+    ```
+
+### `from_nttp(Quantity<U, R>::NTTP)`
+
+Calling `from_nttp` on a `Quantity<U, R>::NTTP` will convert it back into the corresponding
+`Quantity<U, R>` that was encoded in the template parameter.  This lets it automatically participate
+in all of the usual `Quantity` operations and conversions.
+
+!!! note
+    If you are simply _assigning_ a `Quantity<U, R>::NTTP` to a `Quantity<U, R>`, where `U` and `R`
+    are identical, you do not need to call `from_nttp`.  We support implcit conversion in that case.
+
 ## Operations
 
 Au includes as many common operations as possible.  Our goal is to avoid incentivizing users to