Support adding and subtracting Constant (#657)

Now that we have `UnitSum<...>` in place, it has become straightforward
to get the labels we want.

The trickiest bit here is when the constant fully cancels additively.
Recall that we are grouping inputs according to the _unscaled_ units
(roughly corresponding to "actual unit symbols").  When every unscaled
unit additively cancels _individually_, the result is zero.  When we end
up with multiple unscaled units which nevertheless cancel together, we
represent that as-is, and don't try to cancel it, because this is also
how we handle input units in multiplication and division.  But the
result is still not-a-unit!  And we have the static assert from the
parent.

From an external user's point of view, we simply recommend that they
_not try to form_ any `Constant` that additively cancels, regardless of
whether it produces `Zero` or a compiler error.  This is a weird thing
to do that probably doesn't have any actual use cases.  We already don't
support all combinations of inputs, and don't plan to, and this feels
like a safe "starter policy" at the very least.

Fixes #607.

Author: chiphogg

au/constant.hh

@@ -211,4 +211,35 @@ constexpr Zero operator%(Zero, Constant<U>) {
     return {};
 }
 
+// Addition (+) for `Constant`.
+template <typename U1, typename U2>
+constexpr auto operator+(Constant<U1>, Constant<U2>) {
+    return make_constant(UnitSum<U1, U2>{});
+}
+
+// Subtraction (-) for `Constant`.
+template <typename U1, typename U2>
+constexpr auto operator-(Constant<U1>, Constant<U2>) {
+    using NegU2 = decltype(U2{} * Magnitude<Negative>{});
+    return make_constant(UnitSum<U1, NegU2>{});
+}
+
+// Arithmetic operators mixing `Constant` with `Zero`.
+template <typename U>
+constexpr Constant<U> operator+(Constant<U>, Zero) {
+    return {};
+}
+template <typename U>
+constexpr Constant<U> operator+(Zero, Constant<U>) {
+    return {};
+}
+template <typename U>
+constexpr Constant<U> operator-(Constant<U>, Zero) {
+    return {};
+}
+template <typename U>
+constexpr auto operator-(Zero, Constant<U>) {
+    return -Constant<U>{};
+}
+
 }  // namespace au

au/constant_test.cc

@@ -523,5 +523,174 @@ TEST(Constant, OrderingWorksWithScaledConstants) {
     EXPECT_THAT(double_c, Gt(half_c));
 }
 
+TEST(ConstantAddition, SameConstantsDoubleTheValue) {
+    constexpr auto one_foot = make_constant(feet);
+    constexpr auto result = one_foot + one_foot;
+    EXPECT_THAT(result,
+                AllOf(Eq(make_constant(feet * mag<2>())), ConstantLabelIs(StrEq("[2 ft]"))));
+}
+
+TEST(ConstantAddition, ResultTypeIsConstantOfUnitSum) {
+    using OneFoot = Constant<Feet>;
+    using OneInch = Constant<Inches>;
+    using ResultUnit = UnitSum<Feet, Inches>;
+    StaticAssertTypeEq<decltype(OneFoot{} + OneInch{}), Constant<ResultUnit>>();
+}
+
+TEST(ConstantAddition, DifferentUnitsProduceUnitSum) {
+    constexpr auto one_foot = make_constant(feet);
+    constexpr auto one_inch = make_constant(inches);
+    constexpr auto result = one_foot + one_inch;
+    EXPECT_THAT(
+        result,
+        AllOf(Eq(inches(13)), ConstantLabelIs(AnyOf(StrEq("(ft + in)"), StrEq("(in + ft)")))));
+}
+
+TEST(ConstantAddition, DifferentScalesOfSameUnitCombine) {
+    constexpr auto two_feet = make_constant(feet * mag<2>());
+    constexpr auto three_feet = make_constant(feet * mag<3>());
+    constexpr auto result = two_feet + three_feet;
+    EXPECT_THAT(result,
+                AllOf(Eq(make_constant(feet * mag<5>())), ConstantLabelIs(StrEq("[5 ft]"))));
+}
+
+TEST(ConstantAddition, OppositeConstantsCancelToZero) {
+    constexpr auto one_foot = make_constant(feet);
+    constexpr auto neg_foot = -one_foot;
+    StaticAssertTypeEq<decltype(one_foot + neg_foot), Zero>();
+}
+
+TEST(ConstantAddition, PartialCancellationLeavesRemainder) {
+    constexpr auto three_feet = make_constant(feet * mag<3>());
+    constexpr auto neg_two_feet = make_constant(feet * (-mag<2>()));
+    constexpr auto result = three_feet + neg_two_feet;
+    EXPECT_THAT(result, AllOf(Eq(make_constant(feet)), ConstantLabelIs(StrEq("ft"))));
+}
+
+TEST(ConstantAddition, AddingZeroReturnsOriginal) {
+    StaticAssertTypeEq<decltype(Constant<Feet>{} + ZERO), Constant<Feet>>();
+}
+
+TEST(ConstantAddition, ZeroPlusConstantReturnsConstant) {
+    StaticAssertTypeEq<decltype(ZERO + Constant<Feet>{}), Constant<Feet>>();
+}
+
+TEST(ConstantAddition, MultipleUnitsCollectLikeTerms) {
+    constexpr auto two_feet = make_constant(feet * mag<2>());
+    constexpr auto one_inch = make_constant(inches);
+    constexpr auto one_foot = make_constant(feet);
+    constexpr auto result = two_feet + one_inch + one_foot;
+
+    EXPECT_THAT(
+        result,
+        AllOf(Eq(inches(37)), ConstantLabelIs(AnyOf(StrEq("(in + 3 ft)"), StrEq("(3 ft + in)")))));
+}
+
+TEST(ConstantSubtraction, SameConstantsYieldZero) {
+    constexpr auto one_foot = make_constant(feet);
+    StaticAssertTypeEq<decltype(one_foot - one_foot), Zero>();
+}
+
+TEST(ConstantSubtraction, ResultTypeIsConstantOfUnitSum) {
+    using OneFoot = Constant<Feet>;
+    using OneInch = Constant<Inches>;
+    using NegInch = decltype(Inches{} * (-mag<1>()));
+    using ResultUnit = UnitSum<Feet, NegInch>;
+    StaticAssertTypeEq<decltype(OneFoot{} - OneInch{}), Constant<ResultUnit>>();
+}
+
+TEST(ConstantSubtraction, DifferentUnitsProduceUnitSum) {
+    constexpr auto one_foot = make_constant(feet);
+    constexpr auto one_inch = make_constant(inches);
+    constexpr auto result = one_foot - one_inch;
+
+    EXPECT_THAT(result, AllOf(Eq(inches(11)), ConstantLabelIs(StrEq("(ft - in)"))));
+}
+
+TEST(ConstantSubtraction, DifferentScalesOfSameUnitCombine) {
+    constexpr auto five_feet = make_constant(feet * mag<5>());
+    constexpr auto two_feet = make_constant(feet * mag<2>());
+    constexpr auto result = five_feet - two_feet;
+    EXPECT_THAT(result,
+                AllOf(Eq(make_constant(feet * mag<3>())), ConstantLabelIs(StrEq("[3 ft]"))));
+}
+
+TEST(ConstantSubtraction, SubtractingZeroReturnsOriginal) {
+    StaticAssertTypeEq<decltype(Constant<Feet>{} - ZERO), Constant<Feet>>();
+}
+
+TEST(ConstantSubtraction, ZeroMinusConstantReturnsNegative) {
+    StaticAssertTypeEq<decltype(ZERO - Constant<Feet>{}), decltype(-Constant<Feet>{})>();
+}
+
+TEST(ConstantSubtraction, SubtractingNegativeAdds) {
+    constexpr auto one_foot = make_constant(feet);
+    constexpr auto neg_foot = -one_foot;
+    constexpr auto result = one_foot - neg_foot;
+    EXPECT_THAT(result,
+                AllOf(Eq(make_constant(feet * mag<2>())), ConstantLabelIs(StrEq("[2 ft]"))));
+}
+
+TEST(ConstantSubtraction, ResultCanBeNegative) {
+    constexpr auto two_feet = make_constant(feet * mag<2>());
+    constexpr auto five_feet = make_constant(feet * mag<5>());
+    constexpr auto result = two_feet - five_feet;
+    EXPECT_THAT(result,
+                AllOf(Eq(make_constant(feet * (-mag<3>()))), ConstantLabelIs(StrEq("[-3 ft]"))));
+}
+
+TEST(ConstantAddition, FractionalCoefficientsWork) {
+    constexpr auto half_foot = make_constant(feet / mag<2>());
+    constexpr auto quarter_foot = make_constant(feet / mag<4>());
+    constexpr auto result = half_foot + quarter_foot;
+    EXPECT_THAT(result,
+                AllOf(Eq(make_constant(feet * mag<3>() / mag<4>())),
+                      ConstantLabelIs(StrEq("[(3 / 4) ft]"))));
+}
+
+TEST(ConstantAddition, CommutativeProperty) {
+    constexpr auto one_foot = make_constant(feet);
+    constexpr auto one_meter = make_constant(meters);
+    EXPECT_THAT(one_foot + one_meter, Eq(one_meter + one_foot));
+}
+
+TEST(ConstantSubtraction, AntiCommutativeProperty) {
+    constexpr auto one_foot = make_constant(feet);
+    constexpr auto one_meter = make_constant(meters);
+    EXPECT_THAT(one_foot - one_meter, Eq(-(one_meter - one_foot)));
+}
+
+TEST(ConstantAddition, NegativeFirstTermShowsMinusPrefix) {
+    constexpr auto neg_foot = make_constant(feet * (-mag<1>()));
+    constexpr auto one_inch = make_constant(inches);
+
+    // Positive coefficients come before negative, so result is (in + (-ft)) = (in - ft).
+    constexpr auto result = neg_foot + one_inch;
+    EXPECT_THAT(result, ConstantLabelIs(StrEq("(in - ft)")));
+}
+
+TEST(ConstantAddition, BothNegativeShowsMinusSigns) {
+    constexpr auto neg_foot = make_constant(feet * (-mag<1>()));
+    constexpr auto neg_inch = make_constant(inches * (-mag<1>()));
+
+    // Both negative, order depends on InOrderFor.
+    constexpr auto result = neg_foot + neg_inch;
+    EXPECT_THAT(result, ConstantLabelIs(AnyOf(StrEq("(-in - ft)"), StrEq("(-ft - in)"))));
+}
+
+TEST(ConstantAddition, ScaledUnitsShowScaleInLabel) {
+    constexpr auto two_feet = make_constant(feet * mag<2>());
+    constexpr auto three_inches = make_constant(inches * mag<3>());
+    constexpr auto result = two_feet + three_inches;
+    EXPECT_THAT(result, ConstantLabelIs(AnyOf(StrEq("(2 ft + 3 in)"), StrEq("(3 in + 2 ft)"))));
+}
+
+TEST(ConstantSubtraction, NegativeFractionalScaleShowsCorrectly) {
+    constexpr auto one_foot = make_constant(feet);
+    constexpr auto three_quarters_inch = make_constant(inches * mag<3>() / mag<4>());
+    constexpr auto result = one_foot - three_quarters_inch;
+    EXPECT_THAT(result, ConstantLabelIs(StrEq("(ft - (3 / 4) in)")));
+}
+
 }  // namespace
 }  // namespace au

docs/reference/constant.md

@@ -574,3 +574,47 @@ constexpr auto seven_inches = make_constant(inches * mag<7>());
 // 5 feet = 60 inches; 60 % 7 = 4
 constexpr auto result = five_feet % seven_inches;  // Constant representing 4 inches
 ```
+
+### Addition and subtraction †
+
+Two `Constant` instances of the same dimension can be added or subtracted, producing a new
+`Constant`.  Like other `Constant` operations, this is performed purely at compile time.
+
+!!! warning
+    Unlike "core" operations, such as powers and products, `Constant` is not fully closed under
+    addition and subtraction.  If the inputs completely additively cancel, the result will either be
+    `Zero`, or else a compile time error.
+
+    Users should generally avoid forming this kind of `Constant`.
+
+`Constant` also interacts with `Zero` for addition and subtraction:
+
+- Adding `Zero` to a `Constant` (in either order) returns the original `Constant`.
+- Subtracting `Zero` from a `Constant` returns the original `Constant`.
+- Subtracting a `Constant` from `Zero` returns the negation of that `Constant`.
+
+† _This feature is subject to the same [compile-time arithmetic
+limitations](./magnitude.md#compile-time-arithmetic-limitations) as `Magnitude` arithmetic, because
+the computation is built on `Magnitude` operations._
+
+**Syntax:**
+
+For `Constant` instances `c1` and `c2` with the same dimension:
+
+- `c1 + c2`
+- `c1 - c2`
+
+**Result:** Whenever the result is nonzero, a new `Constant` representing the sum or difference.
+
+**Example:**
+
+```cpp
+constexpr auto one_foot = make_constant(feet);
+constexpr auto one_inch = make_constant(inches);
+
+// Sum of 1 foot and 1 inch
+constexpr auto sum = one_foot + one_inch;  // Constant representing (ft + in)
+
+// Difference
+constexpr auto diff = one_foot - one_inch;  // Constant representing (ft - in)
+```